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Information about this Manual 

Review the following itens before you read this publication. 

The subject of this manual 

This manual describes features of the Command Interpreter Program (CIP) 
and system calls in the WMCS operating system that have been added since 
the WMCS manuals were printed in May 1985 . 

The audience for whom this publication was written 

This manual is written for users who have read the WMCS User's Reference 
Manual and the various utilities manuals, for system managers who have 
read the WMCS System Manager's Reference jaanualc aug Ist£ 
programmers who have read the WMCS Programmer' s Reference Manual^ 

.Belated obligations 

WMCS User's Reference Manual 

WMCS System Manager's Reference Manual 

WMCS Programmer's Reference Manual 



Typographical Conventions Used in this Publication 

Bold facing indicates what you should type. 

Square brackets, [], indicate a function key, the name of which appears 
in uppercase within the brackets. For example, [RETPtf] , [CTRL] , etc. 
Braces, {}, indicate a key in the keypad. 

Underlining is used for emphasis. 
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Chapter 1 
User's Reference 



The WMCS User's Reference Manual describes the Command Interpreter 
Program (CXP). 

This chapter explains modifications that have been made to WMCS 
functions, the Command Interpreter Program (CIP) , and CXP commands since 
the last printing of the WMCS User's Reference Manual (May 1985) . The 
chapter also describes five new CIP commands: asap, confer , defrag, 
dmapper, and make . 



New Features and Modifications in the CXP 

This section describes modifications and additions to the CI P. 



On computers that use SCSI disk or tape drives, such as the 
System 1250, System 1255, and System 1260, these are the default 
devicenames for the drives: 

Device Name Device 

_ST0 SCSI cartridge tape drive 

SD0 SCSI hard disk drive 



Significant Command-line Characters 

The character sequence //# has been added to the list of significant 
command-line characters. Also, the function of the double quotation 
mark has been modified. 
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//# Double Slash, Number Sign 

The douhle slash, number sign sequence, //#, is used to open a disk 
device as if it were a file. When a disk is opened this way, you 
can read from it and write to it as if it were a file (that is, the 
effect is the same as if you had mounted the disk with the mnt 
command using the : special switch) . The double slash and" number 
sign must immediately follow the devicename, as in the following 
examples: 

_sd0//# _dc0//# 

" Double Quotation Mark 

Switch names are no longer recognized when they are enclosed in 
double quotation marks. For example, the CEP no longer recognizes 
the :since= switch in the following example: 

":since=today n 



Modifications to WMCS Ffcmctions 

These are the modifications that have been made to WMCS functions. 



The format for broadcast message has changed. A header line has 
been added that displays username, source device, and current time. 
The message format was also modified to autowrap the message at the 
port's screen width (defined by dstat) . If the screen width is below 
the minimum (20) , the width will be set to the minimum. A width of 
zero will be mapped to 80. 

These commands are affected: 

keygen qprint recover send 

shutdown wait watchdog 



File lYres 



A :f iletype= switch has been added to allow the user to control the 
type of files being generated. 
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The following file types are supported directly by the WMCS 
Name Value Description 



DATA 





normal data file 


DIRECTORY 


1 


directory file 


IMAGE 


2 


image file 


KSAMDATA 


3 


KSAM data file 


KSAMKEY 


4 


KSAM key file 


LLIMSGE 


5 


11 image file 


ARCHCDNT 


6 


archive continuation file 


ENCRYPT 


7 


encrypted file 


SYSTEM 


8 


system file 


ARCHIVE 


9 


archive file 


CTPCMD 


10 


cip and file 


OCBOL 


11 


CCBOL file 


BASIC 


12 


BASIC file 


PASCAL 


13 


Ifcscal file 


OBJECT 


14 


object file 



File types from 15-255 are reserved for future use by WMCS. File 
types from 256-65535 are available for user definition. 

Aliases for user file types can be imp! oriented using logical names. 
Two logical names are required. 

For example, to implement file type 300 and call it MYFILETYPE, the 
logical nanes to get the correct translations are: 

> M @filetype300" := myfiletype 

> "@myfiletype" := 300 

When using the :filetype= switch, unique abbreviations are allowed 
for all file-type names except user aliases, which must be 
compLetely spelled out. Valid characters for user file-type aliases 
are alphanumerics and the underscore. 

The following commands are affected ty this change: 

copy create link tcojy 

translit vew 



Pause 



For all commands that have the :pause switch, the length of the 
screen is now specified by the port's screen length (defined by 
dstat ) . 
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The return key, [RETRN] , now advances the dispLay one line. Other 
characters advance the display one screen length as before. 



Terminal Type and Setup Files 

For all utilities that use the terminal- independent screen handling 
routines, the names of the setup files have been changed, The setup 
files used to be found in the directory called SYS$DISK/SYSLIB/, and 
they were called SETUPxxx.SYS, where xxx was a number that indicated 
the terminal type. Setup files are now found in the directory 
called SYS $DISK/SYSL IB. SETUP/. The setup files new have names that 
indicate what type of terminal they represent. The new file 
extension for setup files is .STP. For example, the T7000 setup 
file is now called T7000.STP instead of SETUP252.SYS. Following is 
a list of the old setup files and their new equivalents: 

Old Name New Name 

SETUP255.SYS VISUAL200.STP 

SEIUP254.SYS TVI912C.STP 

SETUP253.SYS MG8000.STP 

SETUP252.SYS T7000.STP 

SETUP251.SYS VT52.STP 

SETUP250.SYS VT100.STP 

SETUP248.SYS HYDRA. STP 

SETUP247.SYS WIT. STP 

SETUP246.SYS 17100. STP 

SETUP256 .SYS IBMPC. STP 

Users' local setup files are now called FTxxx.STP, where xxx is the 
number of the terminal type. The filename (FTxxx) is the same name 
that is used by the dstat command. You may assign a name to be used 
for your setup file and for the :termtype= switch (in dstat ) by 
setting up two logical names. Following is an example of defining 
terminal type 5 to be a Beehive terminal. 

> "§ft5" := "beehive" 

> "a«efaive" := "ft5" 

With these definitions, the setup file in SYS $DISK/SYSL IB. SETUP/ 
would be called BEEHIVE. STP. 

All of the commands that use the terminal- independent screen 
handling routines have :setupin= and :setupout= switches. These 
switches define which setup file to use for both input and output. 
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There are now four ways you can specify a setup file: 

1. Specify nothing (this is the default). In this case, the 
QP looks in the directory SYS $DISK/SYSL IB. SETUP/ for the 
setup file that matches the terminal type named by dstat . 

2. Specify a filename (for example, T7000) . In this case, the 
CEP looks in the directory SYS $DISK/SYSLIB. SETUP/ for a 
file with the name you specified (the QP appends the .STP 
extension if you did not specify it) . 

3. Specify a pathname (for example, SYS $DISK/USERS. SETUP/) . In 
this case, the CEP looks in the directory you specified for 
the setup file that matches the terminal type named by 

flstat. 

4. Specify a pathname and a filename (for example, SYSSDISK / 
USERS. SETUP/ABC) . In this case, the QP looks for the 
setup file you specified in the directory you specified 
(the QP appends the .STP extension to the filename if you 
did not specify it) . 

The QP first searches for a setup file with the new name style. If 
the file cannot be found, the CEP searches for a setup file with the 
old name style. If that file cannot be found, an error is reported. 

The following commands are affected by this change: 

eta nsysprof nuserprof sysprof 

user prof vew zap 



Wil dear dina 

For. commands that use wildcarding, three new switches have been added, 
and one switch has been modified. The switches are these: 

:class= Type a list of device classes separated by commas. 

Only files that reside on the class (es) of devices 
given will be included in the list of files returned. 
The default is all classes. 



1-5 



User's Reference 

Valid device classes are: 



tty 


TTYS pecial 


Pipe 


PipeSpecial 


Tape 


TapeSpecial 


Sync 


SyncSpecial 


Disk 


Disks pecial 


Queue 


Queues pecial 


Network 


Networks pecial 


NonDev 


NonDev Special 


TTYNetwork 





:filesize= Type a numeric range of file sizes in Kbytes. Only 
files that fall within the specified size range will 
be included in the list of files returned. The 
default is all files (range 0-). 

:typeselect= Type a list of file-type names (including user 
definable names) and/or ranges of file-type numbers. 
Files that match the set of specified file types are 
included in the set of files returned. 

Default file-type names are: 

Archive Data KsamKey 

ArchiveCbnt Directory LLImage 

Basic Encrypted Object 

CI Pcmd Image lascal 

Cbbol KsamData ^stem 

See the File Types section of this addendum for more 
information on file types and their values. 

:sort= TWo additional sort options have been added, FILESIZE 

and FILETYEE (numeric value) . The default is to sort 
based on filename. 

The following commands are affected by these changes: 



arch 


backup 


checksum 


co£Y 


count 


crypt 


del 


dir 


dump 


fstat 


install 


print 


pu 


ren 


restore 


scan 


tcory 


translit 


type 


typemrl 



usscopy version wscan wsort 



1-6 



User's Reference 



Modifications to GCP Qranands 

The following CIP commands have been modified as described below. 



B3?KUP 



A :edit= switch has been added. This allows you to change the 
directory names that are placed inside the arch files. In other 
words, you can use the :edit switch with backup so you do not have 
to use it later with restore . 



BKup 



The SCSI tape name of ST0 has been added to the list of valid 
devices on which bkup can make a backup of software programs. 



BtUP 



The units of the :cache= and :usercache= switches for disk class 
devices have been changed from sectors to Kbytes. Also, the display 
of these fields has been changed to Kbytes. 

The values for the :drivetype= switch have been modified. These are 
the valid drive types that can be used: 



Drive Type 

ELOP09A 

ELOP09B 

ELOP015 

WIN12 

WIN19 

WIN30 

WIN43 

WIN48 

WIN86 

WIN101 

WIN141 - 

WIN182 

SMD84B 

SMD168B 

SMD474B 

SMD515B 

SLBDISKA 

SUBDISKB 



Description 



5 .25-inch floppy 

5. 25- inch floppy (5 sector) 

8-inch floppy 

12 Mbyte 5 .25- inch Winchester 

19 Mbyte 5 .25-inch Winchester 

36 Mbyte 5 .25- inch Winchester 

43 Mbyte 5.25-inch Winchester 

48 Mbyte 5 .25- inch Winchester 

86 Mbyte 5.25-inch Winchester (SCSI only) 

101 Mbyte 5.25-inch Winchester (SCSI only) 

141 Mbyte 5.25-inch Winchester (SCSI only) 

182 Mbyte 5. 25- inch Winchester (SCSI only) 

84 Mbyte SMD disk 

169 Mbyte SMD disk 

474 Mbyte SMD disk 

516 Mbyte SMD disk 

512 Kbyte subdisk (0.5 Kbytes per sector) 

512 Kbyte subdisk (1 Kbyte per sector) 
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The following drive types are no longer valid with the :drivetype= 
switch: 



IMI20 
IMI40 



20 Mbyte IMI disk 
40 Mbyte imi disk 



The checksum command has been modified to dispLay the filename and 
date as soon as the file is opened. After the filename and date 
have been displayed, the checksum is calculated. 

A :edit= switch was added to checksum . You can new control the name 
of the file created by checksum . This makes checksum files (for 
later use by verify) much more flexible. 



QlKti 



The following switches were added to chkd : 



:bac= 



ibadonly 



If specified, this switch marks the range of 
sectors bad in the bitmap of the device, 
without checking the sectors. 

If specified, only those sectors already 
marked bad on the device are checked. The 
default checks all sectors. 



:bitmap= 



: check 



If specified, this switch defines the name of 
a generated bitmap file to use instead of the 
standard one in /KXfUDIB/ . It uses only the 
bad portion of the alternate bitmap file. 

If :nocheck is specified, the disk is not 
checked, and the current state of the disk is 
displayed. The default is to check. 
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icheckallocated When a disk is checked, only sectors allocated 
to a file are read, and unallocated sectors 
have a pattern written to them. Then the disk 
is verified by reading back the sectors to see 
if the pattern is the sane. If this switch is 
specified, even sectors that are allocated to 
files have a pattern written to them. Chkd 
first reads and saves the original data, then 
writes its pattern and verifies it, and 
finally restores the original data. 



NOTE: Data can be lost if the system goes down 
in the middle of this operation or if 
the original data cannot be rewritten. 
The default is to not write check 
allocated sectors. 



: confirm 



:gooc= 
:f iles 



If specified, then user confirmation is asked 
for each time a sector should be changed in 
the bitmap file (that is, each time a sector 
that was marked good will be marked bad, or 
each time a sector that was marked bad will be 
marked good) . The default is to not confirm. 

If specified, this switch marks the range of 
sectors good in the bitmap of the device. 

If mofiles is specified, the filenames of 

sectors marked bad (in files) are not 

displayed. The default is to display these 
filenames. 



:keepbad= 



If specified, this switch defines the name of 
a bitmap to use instead of the standard file 
in /RDOTDIR/. Only the bad portion of this 
alternate bitmap file is written. 



Chkd can now check the sectors on a disk that is mounted special. A 
bitmap form of this output can be saved with the :keepbac= switch. 
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Q?nfjq 



Confia has been updated to allow the specification of the FFOINT and 
NETWORK class handlers. It has also been updated to handle all of 
WIGVT Systems' current model numbers and the SCSI disk device 
driver. 



CfrPf 



A rdelete switch has been added. It causes the destination file to 
be deleted automatically if copy is terminated before an entire file 
is copied. The default is to delete files not completely copied. 



Crypt 



A :verify switch has been added. It requests that the key be entered 
twice and verified if the key is not input on the command line. The 
default is to verify. 

A rdelete switch has been added. It causes a file to be deleted 
automatically if crypt is terminated before an entire file is 
encrypted or decrypted. The default is to delete files not fully 
copied. 



The dev command now displays the new TTYNET class of devices. 

Dinit 

Dinit now has the ability to format selective tracks on a disk. By 
default it reads all the data it can from a track before formatting 
it, and then restores the data it read back to the track after 
formatting. It will not preserve data if the :nof ilesys switch is 
used. 

Also, dinit now checks for bad sectors while writing the four system 
files. It then maps around the bad sectors. 

The definition for the :cache= and :usercache= switches for disk 
class devices has been changed. Instead of being in sectors, the 
cache size is now in Kbytes. Also, the defaults for these parameters 
are now based on the size of the disk. 

The default sizes of the :ialloc= and :alloc= switches have been 
changed to be dependent on the size of the disk. 
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The following switches have been added to dinit : 
rkeepbad 



This switch specifies that we should read the 
current state of the bad portion of the bitmap 
file and save it before initializing the disk. 
This way bad sectors stay marked across uses of 
dinit . The default is to preserve bad sectors 
across uses of dinit . 



ikeepbacb This specifies an alternate bitmap file (for 

preserving bad sectors) other than the standard 
file in /RDCTDIR/. Any valid file designation 
may be specified. 

rverbose Display explanatory messages while performing the 

deinitialization. The default is to display 
verbose messages. 

:track= This switch formats the specified range of tracks 

only. It preserves what data it can from the 
track (s) unless the mofilesys switch is 
specified. 

:sector= This switch formats the track (s) that the range 

of sectors is on. It preserves what data it can 
from the track (s) unless the mofilesys switch is 
specified. 

:subdkfname= If this switch is used for a subdisk device, it 
specifies the filename of the subdisk. 

:subdksize= If this switch is used for a subdisk device, it 
specifies the maximum size (in sectors) of the 
subdisk being created. 
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The values for the :drivetype= switch have been modified, following 
is the list of valid drive types that can be used: 



Drive Type 

ELOP09A 

5LOP09B 

ELOP015 

WIN12 

WIKL9 

WIN30 

WIN43 

WIN48 

WIN86 

WIN101 

WIN141 

WML 82 

SMD84B 

SMD168B 

SMD474B 

SMD515B 

SUBDISKA 

SLJBDISKB 



Description 



5.25-inch floppy 

5. 25-inch floppy (5 sector) 

8-inch floppy 

12 Mbyte 5 .25-inch Winchester 

19 Mbyte 5 .25-inch Winchester 

36 Mbyte 5 .25- inch Winchester 

43 Mbyte 5 .25-inch Winchester 

48 Mbyte 5. 25- inch Winchester (WPC or SCSI) 

86 Mbyte 5.25-inch Winchester (SCSI only) 

101 Mbyte 5. 25- inch Winchester (SCSI only) 

141 Mbyte 5.25-inch Winchester (SCSI only) 

182 Mbyte 5. 25- inch Winchester (SCSI only) 

84 Mbyte SMD disk 

169 Mbyte SMD disk 

474 Mbyte SMD disk 

516 Mbyte SMD disk 

512 Kbyte subdisk (0.5 Kbytes per sector) 

512 Kbyte subdisk (1 Kbyte per sector) 



The following drive types are no longer valid with the :drivetype= 
switch: 



IMI20 
IMI40 



20 Mbyte IMI disk 
40 Mbyte IMI disk 



J2L 



A refresh- screen command has been added. It is 
the refresh-screen command in CEP and VEW) . 



[CTRL] -(the same as 



Pstat 



The display of dstat has been modified to be more logical. Also, a 
line has been inserted, defining the class of the fields being 
displayed. 
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The following switches have been added: 

rnetwork This switch allows a user to switch a TTY line in 

and out of network mode. 

:preanpt This switch specifies that a given TTY port 

should run with preemptive interrupt enabled. 

:length= This switch allows the user to define the number 

of lines on the terminal screen. The default is 
24. 

:width= This switch allows the user to define the number 

of columns on the terminal screen. The default is 
80. 

: reset This switch resets the TTY class device. 

When a port is set to autobaud mode, the port's baud rate is set to 
19200 baud. This is a problem if it is a modem port that you also 
want to talk out of. To solve this problem, an alternate baud rate 
has been implemented. A DSTYTTYALTBAUD field has been added to the 
device-status block for the TTY driver. Whenever a new baud rate is 
set into the DSTYM0DERB32 field for a device (and that device is 
using the TTY driver) , the baud rate is also inserted into the 
DSTYITYALTBAUD field. This works by having the port normally set to 
19200 baud for autobaud input. However, if the port is opened by a 
process (and there are no other users of the port) , the _open SVC 
switches the baud rate on the port to the alternate baud rate 
specification. Note that dstat sets the baud rate into both of 
these fields when the :baud= switch is used. 



Dump<3iff 

A : rewind switch has been added. 



Fstat 



A :extents switch has been added so that each extent in the file's 
FCB can be displayed. 
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The SCSI tape name of SIB has been added to the list of valid 
devices from which load can load software programs. 



Logon 



If a user does not log on in five tries, logon now hangs up on 
SYS$INKJT. If the port is connected to a modem, it is disconnected. 
This makes it harder for people to break into a system across a 
modem. 

If a user logs on to a remote machine, logon clears out all remote 
association with the original machine. This makes logging on to a 
remote machine function exactly like logging on to a local machine. 

Logon now changes the UIC to that of the user logging on before it 
changes to the user's desired directory. This enables users to have 
their default directory on a machine other than the machine they 
logged on to. 



The following switches have been added: 

:strip= If the : simple switch is also specified, : strips 

defines how many bytes of data are to be stripped 
from the front of the file. The default is 1024 
bytes. 

:control= This switch works only if the isimple switch is 

specified. It has four values: 

NCNE - Gopy from the end of the stripped 
data to the end of the file. 

BYTE - Immediately after the stripped data, 
there is a byte-wide count of the 
number of bytes of data to copy. 
Starting with the byte containing the 
count, copy for the specified number 
of bytes. 
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WORD - Immediately after the stripped data, 
there is a word-wide count of how 
many bytes of data to copy. Starting 
with the first byte of the word 
containing the count, copy for the 
specified number of bytes. 

LONG - Immediately after the stripped data, 
there is a longvord-wide count of how 
many bytes of data to copy. Starting 
with the first byte of the lonc^ord 
containing the count, copy for the 
specified number of bytes. 

For the byte, word, and long values, after the 
amount of data is copied, makedsr will check to 
see if a version string immediately follows. If 
so, it will be copied also. 



A :subdkfname= switch has been added. If you are mounting a subdisk 
device, this switch defines the name of the disk file to use. Any 
valid file designation may be specified. 
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The values for the :drivetype= switch have been modified, following 
is the list of valid drive types that can be used: 



Drive Type 

ELOP09A 

FLOP09B 

ELOP015 

WIN12 

WIN19 

WIN30 

WIN43 

WIN48 

WIN86 

WIN101 

WINL41 

WIN182 

SMD84B 

SMD168B 

SMD474B 

SMD515B 

SUBDISKA 

SUBDISKB 



Description 



5.25-inch floppy 

5.25-inch flopjy (5 sector) 

8-inch floppy 

12 Mbyte 5 .25- inch Winchester 

19 Mbyte 5.25-inch Winchester 

36 Mbyte 5 .25-inch Winchester 

43 Mbyte 5 .25-inch Winchester 

48 Mbyte 5 .25- inch Winchester 

86 Mbyte 5.25-inch Winchester (SCSI only) 

101 Mbyte 5. 25- inch Winchester (SCSI only) 

141 Mbyte 5.25-inch Winchester (SCSI only) 

182 Mbyte 5 .25- inch Winchester (SCSI only) 

84 Mbyte SMD disk 

169 Mbyte SMD disk 

474 Mbyte SMD disk 

516 Mbyte SMD disk 

512 Kbyte subdisk (0.5 Kbytes per sector) 

512 Kbyte subdisk (1 Kbyte per sector) 



The following drive types are no longer valid with the :drivetype= 
switch: 



IMI20 
IMI40 



20 Mbyte IMI disk 
40 Mbyte IMI disk 



Nuserprof 



A comment field has been added to each record in the display. This 
allows users to better keep track of the purpose of each record. 
This also means that the /SYSLJB/NETUAF.D&T file has changed format. 
Nuserprof automatically converts files from the old format file to 
the new format. 

The :setupin= and :setupout= switches are now used by Nuserprof . 



Print 



Print has been modified to make the file parameter handle up to 256 
characters. Longer file lists are now possible. 
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Qprint 

Qprint has been changed to write data to SYSSOUTHJT. 

The : allocate switch has been added for those users that want to run 
Qprint through a pipe or directly to a disk file. They can specify 
:noallocate and qprint does not allocate the device. 



Shloa 



If a logical name crosses more than one line, shloq wraps it 
automatically. 

The :user switch was added to display user process logical names. 
The default is to display user process logical names. 

The :system switch has been changed to cause shloq to display system 
logical names. 



Shutdown 



.SB. 



A : stats switch has been added that causes shutdown to display the 
system's status (using the command pstat rheader :systemstatus 
:port :status :size -.priority '.scheduled -.timeslice) immediately on 
startup, and after each broadcast. 

If a system on a network is shut down, shutdown sends a message to 
all remote connections that the machine is being shutdown. 

The display of shutdown has been modified to display the node name. 



The :ktytes switched has been removed and replaced fcy the .-sectors 
switch. The default is :no sectors (which means the dispLay is in 
Kbytes) . 



gysprof 



TWo new fields were added to the screen display. They are "SUBDISK 
FILENAME" and "SUBDISK SIZE". If a user is defining a subdisk 
device, the default filename and size of the device can be specified 
here so they do not need to be defined each time the device is 
mounted. 
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Tune 



If the rprompt switch is specified, time displays a date and time 
prcmpt so the user can change it. 



TE3n?lit 



A tdelete switch was added; it causes a file to be deleted 
automatically if translit is terminated before an entire file is 
copied. The default is to delete files not fully copied. 

A :append switch has been added, which allows multiple source files 
to be put together into one destination file. 



Type 



A :tail switch has been added, which when specified with the 
: continuous switch, causes type to start typing at the end of the 
file. 

A :delay= switch has been added, which when specified with the 
: continuous switch, defines how long to pause (in seconds) between 
each poll of the file being typed. The default is 1 second. 



Usscopy 



A :terminate switch has been added. This switch requests that the 
remote system's usscopy be terminated immediately. 

A :receiveonly switch has also been added. Use this switch to 
specify to the background usscopy command that it may only receive 
files, and may not send any files to the local usscopy command. 
Should the local usscopy request the background usscopy to send 
files, it will return an error and terminate. The default is 
moreceiveonly. 



A :allversions switch has been added. It allows users to use 
checksum , and verify multiple versions of the same file. 
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YSL 



A command called J£ has been added that allows the user to set the 
file type of any file subsequently created by VEW. See the File 
Types section for more information about file types. The user may 
specify a file type number or file type name. 

Default file type names are: 

Archive Data KsanKey 

ArchiveOont Directory LLImage 

Basic Encrypted Object 

CEPcmd Image Pascal 

Oobol KsamData ^stem 

The definition of the :memory= switch has been changed. There are 
now 3 states. They are: 

1. If a positive integer is specified, the memory buffer size 
is the lesser of the given number in Kbytes or the size of 
the file plus 4 Kbytes. 

2. If zero is specified, the memory buffer size is the size of 
the file plus 4 Kbytes. 

3. If a negative integer is specified, the memory buffer size 
is the absolute value of the given number in Kbytes. 



Wait 



Wait sets the NCWATCHDOG attribute. Wait is now installed with the 
SETATIR privilege. 



The :polltime= switch has been added to allow the user to specify in 
minutes how often to wake up and check for processes which are to be 
killed. The default value is five minutes. 
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Zap 

A .gb command has been added that allows a user to go to an explicit 
byte in the file. 

A d£ command has been added that allows a user to delete from the 
current position to the end of the file. This command only works 
when zap is being used on a disk file (as opposed to a device) . 



New CEP Oonmands 

This section describes the five new QP commands: 

a sap 

confer 

defrag 

dmapper 

make 
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Functional Description 



Use this command to list, insert, or delete records from the table of 
Create Process Indirection Records. The table of Create Process 
Indirection Records (CPIR) associates an application program with a file 
type. 



Command Line ^ntax 



Mnemonic 

Required 
parameters 

Optional 
parameter 



asap 

File Type (Optional if Function is :list) 
Command Line (Allowed only if Function is : insert] 

Function (: insert, rdelete, rlist) 



Switches 



System 
affected 



:siteic= 



Display 

Function 
modifiers 



:filetype :header 
:auto : confirm 



:log 



: pa use 
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Parameters 



File Type 



Function Required if Function is : insert or : delete; 
optional if Function is :list. Use this 
parameter to specify the file type to insert 
or the file types to list or delete. 

Default None if Function is : insert or : delete. All 
file types if Function is :list. 

Syntax Type a recognized WMCS file type, a file- type 

alias, a numeral, or a range specification 
(range only if Function is :list or : delete) . 



The following file types are supported 
directly by WMCS: 



Name 



Value Description 



DATA 





normal data file 


DIRECTORY 


1 


directory file 


IMAGE 


2 


image file 


KSAMDATA 


3 


KSAM data file 


KSAMKEY 


4 


KSAM key file 


LLIMAGE 


5 


11 image file 


ARCH03NT 


6 


archive continuation file 


ENCRYPT 


7 


encrypted file 


SYSTEM 


8 


system file 


ARCHIVE 


9 


archive file 


CTPCMD 


10 


cip and file 


CCBOL 


11 


CCBOL file 


BASIC 


12 


BASIC file 


PASCAL 


13 


Eascal file 


OBJECT 


14 


object file 



File types from 15-255 are reserved for future 
use by WMCS. File types from 256-65535 are 
available for user definition. 
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NOTE: Aliases for user file types can be 
implemented using logical names. Two 
logical names are required. For 
example, to implement file type 300 and 
call it MYFUiETYPE, the logical names to 
get the correct translations are: 

■*£iletype300" := nyfiletype 
■fryfiletype" := 300 



Valid characters for user file-type aliases 
are alphanumerics and the underscore. The 
maximum length of a user file type is 93 
characters; however, if the length is greater 
that 13 characters, the name will cause the 
:list display of ASAP to shift over. If the 
name is greater than 11 characters, it will be 
truncated in other commands that display file 
types, such as DIR or FSTAT. 



Oommand Line 



Function Required if function is :insert. Otherwise 
not allowed. This line has two functions: 



This string is inserted in front of the 
user's current command line exactly as it is 
defined here. 

This string is scanned from the front, 
looking for the first invalid file character 
(anything that is not alphanumeric, $, or ~) 
or the end of the string. Wherever it 
stops, this will be used as the image 
filename parameter to the create process. 
The old filename parameter is discarded. 

Default None. 

Syntax Type a string containing the desired command 

line. No validation is done on the string. If 
spaces are to be embedded in the string, it 
must be surrounded by double quotes. 
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Function 



Function Optional. Use this parameter to specify 
whether you want to list, insert, or delete 
records in the system CPIR table. 

Default :list if Command Line parameter is not 
specified; : insert if Gommand Line parameter 
is specified. 

Syntax Type one of the following: 

:list to list all the file types that are 
presently entered in the CHR table, along 
with their associated command lines. 

:insert to insert a record into the CPIR 
system table for the file type specified. 

rdelete to delete a record (or records) in 
the CPIR system table for the file type(s) 
specified. 



Switches 



:auto 


Function 




Default 




Syntax 


:conf irm 


Function 




Default 




Syntax 


:f iletype 


Function 




Default 




Syntax 



Use this switch to perform the deletion of 
records in the system CPIR table without any 
confirmation. 
:noauto 
Type :auto 



Use this switch to confirm or deny each file- 
type record on deletion. 
:no confirm 
Type :confirm 



Use this switch to include the numeric file 

type in the :list display. 

:f iletype 

Type :nof iletype to suppress file type in 

:list dispLay. 
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:header 



Function Use this switch to display column headers. 

Default :header 

Syntax Type rnohead to suppress column headings. 



:log 



Function 



Default 
Syntax 



Use this switch to specify whether log 
messages are to be displayed. (Log messages 
are informational displays that indicate what 
the utility is cbing. ) 

The value specified by the option command. 
Type :log or molog to override the default. 



: pause 



Function 



Default 
Syntax 



Use this switch to stop the display after each 
screen of information. The user can then 
press [RETEN] to advance one line, or any 
other character to advance to the next screen. 
The value specified by the option command. 
Type :pause or mopause to override the 
default. 



:siteic>= 



Function Use this switch to specify the system on which 

the action is to take place. 
Default The system on which the calling process is 

executing. 
Syntax Type :siteid= followed by a numeral or 

nodename. 



Examples 



> asap basic ■sys$disk/sysexe.sgs/wbasic.exe ■ : insert 

This command associates the WBASIC interpreter with the file type BASIC, 
The following message appears on the screen: 

Filetype BASIC inserted. 
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> asap :list 

This command lists all the records in the system CPIR table. The 
following type of display appears on the screen: 

Filetype name Ftype Command line 

300 300 n SYS$DISK/USERS.MYDII0 / IYI : ROG.EXE special_parml special 

_parm2 special_parm3 special_parm4 " 
BASIC 12 n SYS$DISK/SYSEXE.93S/WBASIC.EXE " 

CIPCMD 10 "SYSSDISK/SYSEXE/aP.EXE^F^' 

If an alias is defined for the user file type, then the following display 
appears on the screen: 

Filetype name Ftype Command line 

BASIC 12 "SY5$DISK/SYSEXE.33S/WBASIC.EXE " 

QPCMD 10 "SYS^ISIV'SYSEXE/CIP.EXE:CF=" 

MYFILETYPE 300 n SYS$DISK/USERS.MYDIP/MYI : ROG.EXE special_parml special 

_parm2 special_parm3 special_parm4 " 

> asap nyf iletype :delete 

This removes the file type MYFILETYPE from the system CPIR table. The 
following messages appear on the screen: 

Filetype MYFILETYPE 
Delete (Y or N)? > y 
Filetype MYFILETYPE deleted. 

If you type asap :list on the CIP command line, MYFILETYPE will not be 
displayed, and files of that type will not work as pseudo- image files. 

> asap aLpcmd "sys$disk/sysexe/cip.exe:CP=" 

This is the standard asap command that is released in LOCALUP. 00M. It 
allows command files that have a .EXE extension and have a file type of 
CTPQ1D to be executed as if they were programs. Note that the asap 
command line will be inserted in front of the users command line, but 
that the image filename will stop just before the colon. 
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Using Prompts 



> asap :insert 

Filetype > basic 

Command line > "sys$disk/sysexe.sgs/wbasic.exe " 

This performs the same function as the first example. 



Notes on Usage 



The asap ccmmand enables users to associate application programs with 
certain file types. In the first example above, the file type BASIC is 
associated with the WBASIC interpreter. This enables the user to just 
give the name of a basic program (if it has its file type set correctly) 
as if it were a ccmmand. The WMCS will attempt to execute the file as an 
image and fail; then it will look in the system CPIR table to see if an 
alternate ccmmand line for the file type of the file given as the "image" 
is available. If so, then the original command line is appended to the 
alternate ccmmand line, and WMCS again attenpts to execute the ccmmand 
line. If you had a BASIC file called MYFILE.BAS, with its file type 
appropriately set, and if the basic file type was entered into the CPIR 
tables as mentioned above, then the following two command lines would be 
functionally equivalent: 

> wbasic nyfile.bas 

> nyfile.bas 

This utility enables users to define their cwn file types, write an 
application program that works especially with that file type, and just 
give the name of the appropriate data file and the application will be 
invoked automatically. 



Related CEP Commands 



None. 
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Functional Description 



Use this command to initiate or join an interactive conference between 
users on several different terminals. A conference may cross machine 
boundaries. 



Command Line Syntax 



Mnemonic confer 

Required Addressee 
parameter 

Optional Message 
parameter 

Switches 

Addr essee : e xcl ude= 

selection :uic= 

Other :logfile= 
rscroll 
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Parameters 



Addressee 



Function Required. This parameter is used to specify 
the username or terminal (s) with which to 
confer. If the parameter appears to be of the 
form USERNAME or NODE_USERNAME, the utility 
will attempt to join a conference with that 
user. If the attempt fails, it will send a 
message to all terminals with that user's uic. 
If the parameter is a device list, the utility 
will send a message to the devices on the 
list, requesting them to join a conference 
with your username. 

Default None. 

Syntax Type a username or nodename_username, or type 

a list of device names separated by commas. 
Wildcard symbols are allowed. 



Message 



Function Optional. Use this parameter to specify 
additional text for the message sent to each 
addressee. 

Default A generic invitation to confer (Please "CONFER 
nodenamejjsername") , giving your nodename and 
username. 

Syntax Type any desired message, enclosed in double 

quotation marks. To insert special characters 
in the line, accept symbols must be used. 
Escape sequences are not allowed in the 
message. The text of the message will be 
appended to the default message. 



Switches 



:exclude= 



Function Use this switch to exclude devices from the 

device list in the addressee parameter. 
Default All devices that match the device list in the 

addressee parameter are selected. 
Syntax Type :exdud^ followed by a list of device 

designations separated by commas. Wildcard 

characters are allowed. 
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:logf ill 



Function 



Default 
Syntax 



Use this switch to define a file to be used as 

a record of the conference. All text of the 

conference will be copied to the file. This 

switch will also force :scroll mode. 

No record will be kept. 

Type :logfile= followed by the name of the 

file to be used as the record. 



:scroll 



Function Use this switch to start the conference in 
scroll, rather than window, mode. 

Default Start the conference in window mode. 

^ntax Type :scroll to start the conference in scroll 

mode. 



:uic= 



Function Use this switch to select only those devices 
that are part of the list given in the 
addressee parameter and that are owned by the 
specified user or list of users. This also 
forces the utility to recognize the addressee 
parameter as a list of devices. 

Default All devices that match the specified list are 
selected. 

Syntax Type :uic= followed by a list of UICs or 

user names. 



Examples 



1. This example shows the initiation of a two- per son conference by John 
(on _tt22) , who wishes to confer with Fred (who uses terminal _tt23 
on the same computer) . The network node is called QED. 

JOHN> confer _tt23 "I need your aoVice on a problem" 

The foregoing command, when executed by John on _tt22, generates the 
following display on Fred's terminal, _tt23 (if _tt23 has broadcast 
mode enabled) : 



JOHN QED TT22 16-APR-1986 10:03:36.07 

Please "CONFER QED_JCHN" I need your advice on a problem 
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John's terminal dears, and the utility identifies itself on the last 
line of the screen. If any errors occurred in broadcasting the 
message, the errors are displayed on John's screen, John waits for 
Fred to reply. 



2. Continuing the foregoing example, Fred brings his terminal to CIP 
command level and replies to John as follows: 

£RED> confer John 

This command causes the utility to try to connect with the 
CONFER_JOHN process (which should still be running on John's 
terminal) on the same network node as Fred. The two processes begin 
to communicate with each other, and Fred's screen appears as follows 
(in window mode) : 



FRED (QED_TT23) 



<space for Fred' s messages to John> 
JCHN (QEDJTI22) 



<space for John' s messages to Fred> 
CONFER: John accepts conference on QEDJTT22. 
At the same time, John's screen appears as follows (in window mode) : 

— JCHN (QED_TT22) 

<space for John's messages to Fred> 

— FRED (QED_TT23) 



<space for Fred 1 s messages to John> 

CONFER: FRED joining you on QED_TT23. 

At this time, anything typed by either Fred or John will appear in 
the appropriate window on both screens. The lines may.be edited by 
following the usual rules for editing the QP command line. As each 
line is completed, the next line in the window is cleared and used. 
When the last line in a window is completed, the first line will be 
cleared and used. 

Either person may use the confer internal commands to invite others 
to join the conference, change modes, or exit. 
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3. John and Fred in the previous example wish to get Dan's advice. Dan 
works on his own workstation computer, which has the node name DAN. 
Fred will invite Dan by using the [ESC] [ESC] in command of the 
utility. The internal command in has exactly the same effect as the 
command line parameter Addressee. To invite Dan, the prompt would 
be: 

Invlte> dan__dan 

The foregoing command will attempt to connect to the process 
CCNFERJDAN on node DAN. Assuming that Dan is not already in a 
conference, that attempt will fail. The utility will then send a 
message to all terminals on node DAN which have a UIC matching the 
username DAN. Dan will receive this message on his screen (provided 
that he has broadcast mode enabled on his port) : 



FRED __QED_TT23 16-APR-1986 10:33:16.57 
Please "CONFER QED_FRED" 



4. From the above example, Dan may reply with the following command: 

DAN> CONFER QED_ERHD 

The foregoing command causes the utility to try to connect with the 
CCNFER_FRED process on node QED. That connection will result in all 
three processes dividing the screen up into three windows, with the 
third window labeled as follows: 



DAN (DAN_TT0) 



5. Fred wants ideas for the Halloween party, so he types the following 
command: 

MD> confer _ * rlogfile^tw.log "I need ideas for a Halloween arty" 

The foregoing command causes the message to be broadcast to all 
terminals on the local node. It forces the resulting conference into 
scrolling mode, and it records the conference proceedings in the file 
HW.LOG. 
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Using Prompts 



> confer 

Port or User > Jtt23 

This performs the same function as the first example above. 



Notes on Usage 



The confer utility uses the VEW setup files and should operate correctly 
with any terminal type known to VEW. However, the line editing commands 
are those of the CEP, not of VEW. 



Operational ttxfes 

There are two operational modes in confer : window mode and scroll mode. 
These modes are defined as follows. 



Window Mode 

Additional conferees will cause the windows to become smaller and 
smaller. If evenly sized windows do not divide the screen evenly, a 
blank area will be indicated at the bottom of the screen. 

If different users have different screen sizes, the utility will 
operate using the smallest screen size, so that all conferees will 
have a similar display. The right edge of the larger screens will 
be blocked off with a vertical line. When a user leaves the 
conference, the screen will be divided into fewer windows, and the 
total screen size may be increased if the user that left had a 
narrower screen than all remaining conferees. 

Should windows become too small, the conference will be switched 
automatically to scroll mode. 
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Scroll Mode 



Typed lines may be extremely long (up to 1023 characters); long 
lines are scrolled horizontally during input and word-wrapped on 
output. 

Gomments are added to the screen at the third from the last line. 
The oldest comments are scrolled off at the top line. The bottom 
two lines are used for input, for messages, and to display 
interactive data entry of other conferees. Each comment on the 
screen (or in the log file) is preceded by the name of the 
contributor, as in a court reporter's document or a pLay script, 
except for the originators comments, which are preceded by a dash 
('-') instead of a user name. 

Scroll mode is entered in one of five ways: 

1. when any user enters a conference with the :scroll switch 

2. when window sizes grow too small in window mode 

3. when any user executes the [ESC] [ESC] sc command 

4. when any user executes the [ESC] [ESC] if command 

5. when any user opens a log file 

The switch to scroll mode is unilateral and irreversible. All 
terminals switch, and no one can change back. 



Functions Available in confer 

The confer utility has several internal functions available. Each of the 
following functions is executed by first striking [ESC] [ESC] , then 
typing the two-letter mnemonic for the function on the command line that 
appears at the bottom of the screen (the same as other screen-oriented 
utilities such as VEW, Zap, Userprof, etc.). The position of the cursor 
when you initiate any of these functions does not affect the execution of 
the function, and the cursor returns to the same location when the 
function is complete. 
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di 

Dismiss a user frcm the conference, 

FUNCTIONAL DESCRIPTION 

The di function dismisses a user from the conference. It is "unkind" in 
operation, because there is no protection from any user dismissing any 
other user from the conference. The di function will take either a 
username or a nodename-devicename pair as the argument for who to 
dismiss. If a username is specified, all users with that name will be 
dismissed from the conference (except the initiator, if he or she has the 
same username) . 

CORRESPONDING CDNTRCL-KEY HJNCTIONS 

None. 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type di 

This prompt appears at the bottom of the screen: 

Dismiss User name > 

Type either the username or the nodename_devicename given in 
parentheses after each username. Uppercase and lowercase are 
not distinguished. Wildcard characters are permitted. 



Step 3 



Step 4 



Strike [RETM*] 

If any attendee of the conference has the specified username 
or is using the specified device, that attendee is dismissed 
from the conference. 

The following message appears at the bottom of your screen: 
CCNFER: <username or devicename> dismissed. 

Shortly after this message appears, another message appears: 

CCNFER: <username> leaving conference. 

In the foregoing messages, <username> is the name of the user 
that was dismissed. The second message appears at the bottom 
of the screen of all participants in the conference. Also, 
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the following message appears, on the screen of all other 
attendees of the conference, in the window (or on the scroll 
line) of the user who initiated the dismissal: 

«CONFER: <username> dismissed» 

The following message appears at the bottom of the screen of 
the attendee who has been dismissed: 

CCNFER: You have been dismissed by <username> 

This user's confer process is then terminated. 
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ex 

Exit the conference. 

FUNCTIONAL DESCRIPTION 

Ihe ex. function terminates your participation in the conference and 
returns you to the CEP. 

ODRRES BONDING (DNTRCL-KEY EUNCTIONS 

{-} 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type ex 

This message appears at the bottom the screen of all other 
participants of the conference: 

CONFER: <username> leaving conference. 
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if 

Insert a file into the conference for other participants to read. 

FUNCTIONAL DESCRIPTION 

The 1£ function is used to send the text of a file to all participants of 
a conference. The conference will be forced into scroll mode. 

CORRESPONDING CDNTRCL-KEY FUNCTIONS 

None. 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type if 

This prompt appears at the bottom of the screen: 

Insert Filename> 

Step 3 Type the name of the file you wish to send. 

Step 4 Strike [RET3N] 

If the conference was not in scroll mode, it is changed to 
scroll mode, and the following message is displayed on the 
screen of all participants: 

Inserting file <full filename>, press [RETRN] when reaoy 

If any conferee chooses not to view the file, he may press 
[CTRL] c at this point, and the file will not be written on 
his screen. If any character other that [CTRL] c or [RETRN] 
is pressed, the terminal beeps and waits for one of those two 
characters. 

After a conferee presses [RFJERN] , the file begins scrolling 
across his screen. To have time to read the file, he or she 
may use [CTRL] s and [CTRL] q to stop and start (respectively) 
the scrolling. There is no way to stop looking at a file once 
it has started being written to the screen. When the entire 
file has scrolled across the screen, this message appears: 

<full filename> inserted. 
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in 

Invite another user to join your conference, or join your oonf erence with 
another conference. 

EUNCTICNAL DESCRIPTION 

The jn function lets you invite another user or users to join your 
conference that is already in progress, or you can use Jjj to join your 
conference with another conference. This command has the same 
functionality as the addressee parameter at the time confer is executed. 

(DRRESBONDING ODNTRCL-KEY HJNCTIONS 

{enter } 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type in 

This prompt appears at the bottom of the screen: 

Invite> 

Step 3 Type the name of the user or the device name of a port. The 

following message appears at the bottom of the screen: 

OONFER: Inviting <username> 

If the specified user name is not currently logged on, a 
message saying "No devices found." appears on the screen. If 
a nonexistent devicename or unknown username is specified, an 
error message is displayed. 
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rs 

Refresh the screen. 

FUNCTIONAL DESCRIPTION 

The £g function refreshes the display on the screen after a message or 
other interruption has disrupted the display. 

CORRESPONDING OONTRCL-KEY FUNCTIONS 

[CTRL] _ 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 "type rs 

The screen is redisplayed to remove any data that was not 
generated by confer . 
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sa 

Start saving a log file of the conference. 

FUNCTIONAL DESCRIPTION 

The .23 function starts a new log file containing a transcript of the 
conference. If a log file is already being kept, it is closed, and a new 
log file is started. If no name is given in response to the prompt, the 
current log file is closed, and logging will no longer occur. 

CORRESPONDING OONTRCL-KEY FUNCTIONS 

{,} 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type sa 

This prompt appears at the bottom the screen: 

Log Filename> 

Step 3 Type the name of the file to which you wish to begin logging. 

Step 4 Strike [RETFW] 

If the conference was not in scroll mode, it will be changed 
to scroll mode, and all subsequent messages will be written to 
the log file as well as to the screen of each participant in 
the conference. 
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sc 

Start scroll mode. 

FUNCTIONS DESCRIPTION 

The .sc function will initiate scroll mode for the entire conference. 
Scroll mode is entered automatically if the conference is large (if there 
is not enough room on the smallest screen in the conference for at least 
three lines per attendee) , if the j,£ command is used (to allow each 
attendee time to read the file) , or if a log file is requested by any 
conferee. Scroll mode can also be entered using this command, if 
desired. If any attendee of the conference initiates scroll mode, the 
entire conference changes to scroll mode. Once scroll mode is entered, 
the conference will remain in scroll mode until it is terminated. There 
is no way to return to window mode. 

CORRESPONDING ODNTRCL-KEY FUNCTIONS 

None. 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type sc 

This message appears at the bottom the screen of all 
participants of the conference: 

OONFER: Changing to SCRCLL mode. 

If the conference was already in scroll mode, this message 
will appear at the bottom of your screen: 

Already in scroll mode. 
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ss 

Shew the number of participants in the conference, and their names. 

JUNCTIONAL DESCRIPTION 

The _gs_ function prints at the bottom of your screen the total number of 
participants in the conference, their usernames, and their locations 
(nodename/devicename) . The status line has the following format: 

USERJAME (NODEJDEVNAME ) 

If logging is enabled, the status line is also inserted in the log file. 

00RRESPCNDIN3 CCNTROL-KEY RJNCTICNS 

None. 

EXECUTION 

Step 1 Strike [ESC] [ESC] 

Step 2 Type ss 

A message similar to this appears at the bottom of the screen: 

STATUS: 5 persons in conference: JOE(QEDJTTll) FRED(QED 
_TT20) DAN(DANJTI0) JCHN(QED_Trl6) DAVE (DAVE_TT0 ) 
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Any unknown command will generate a help display. The format of the help 
display is this: 

CONFER HELP DISiLAY - Gommands . . . 
DI - Dismiss a user from conference impolitely 
EX - EXit from conference 
IF - Include File 

IN - INvite user <node_username> or terminal < node_terminal> 

RS - Refresh Screen 

SA - SAve a log file of conference 

SC - change to SCroll mode 

SS - Shew Status 

on most terminals: {-} is EX, {enter} is IN, {,} is SA 

The help display is inserted on the screen, starting at the top line. An 
asterisk is displayed on the next-to-last line, indicating that confer is 
waiting for any key to be pressed. When you press a key, signaling that 
you have completed reading the help display, the screen is refreshed. 



Related CIP Commands 



send Send a message to a list of terminals 

talkt Gonnect terminal to another terminal port 
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Functional Description 



Use this command to reorganize a disk, that is, to make files contiguous. 
This reduces seek time, enabling the disk to have better throughput. 



GDmmand Line 


Syntax 








Mnemonic 




defrag 








Required 
parameter 




Devicename 








Optional 
parameter 




Message 








Switches 
Message 




:bell 

: broadcast 








File selection 


:before= 

:mod 

:uic= 


:exclude= 
:since= 


:f iles= 
:sort= 


:f ilesize= 
:typeselect= 


Other 




: condense 
: stats 


:hibernate 
:verbose 


: names 
:verify 


:pause 
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Parameters 



Devicename Function Use this parameter to specify the name of the 

disk whose file system is to be reorganized. 
Default None. 
Syntax Type a valid device designation. 



Message 



Function Use this parameter to specify an optional 
message to all users on the system, informing 
them why the disk is being reorganized, 
probable duration of execution, or other 
message of the operator's choice. 

Default Unless you type rnobroadcast, the following 
kind of message is sent to all users on the 
system: 



SYSTEM NODEJTT0 14-Apr-1986 13:39:11.00 

DEFR£G beginning on _DC0 



Syntax Type a string enclosed in cbuble quotation 

marks. 



Switches 



:bef or< 



Function Use this switch to select only those files 
that match the :files= switch and were 
created/modified before the specified date and 
time. 

Default Selects all files that match the :files= 
switch. 

Syntax Type :before= followed by a date and/or time 

in in the standard date and time syntax. 
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:bell 



Function Use this switch to output a bell along with 
the message (unless suppressed with the 
mobroadcast switch) . 

Default :bell; i.e., a bell is sounded when the 
message is printed. 

Syntax Type mobell to suppress the bell. 



[broadcast Function Use this switch to suppress the broadcast 

message. 
Default rbroadcast; i.e. a message is broadcast to 

every mounted terminal when defrag starts and 

finishes. 
Syntax Type mobroadcast to suppress the broadcast 

message. 



: condense 



Function Use this switch to suppress the condensing of 
extents of files. By default, defrag 
compresses the empty space between extents of 
a file in an attempt to generate larger blocks 
of free space for later use. This is done 
before any files are moved. In some 
instances, such as when defrag has been run 
recently or when more than 50 percent of the 
disk space is free, this condensing is 
unnecessary. 

Default :condense; i.e. 6b the condensing of extents. 

Syntax Type : no condense to suppress the extent- 

condensing section of defrag from executing. 



:exclude= 



Function Use this switch to select only those files 
that match the :f iles= switch and do not match 
any of the files specified as the value of the 
:exclude= switch. 

Default Selects all files that match the :files= 
switch. 

Syntax Type :exclude= followed by a list of file 

designations, separated by commas, any one of 
which may contain wildcard characters. 
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:f iles= 



Function Use this switch to select files to be 
reorganized first. This means that these 
files will be put closer to the center of the 
disk, requiring less seek time from the FCB 
file to the data in the file. 

Default Reorganize files according to file type, then 
by file size within each file type, in this 
order: File system files, DIRECTORY files, 
IMAGE files, all others. 

Syntax Type :files= followed by a list of file 

designations, separated by commas, any one of 
which may contain wildcard characters. 



f il esiz e= 


Function 




Default 




Syntax 


: hibernate 


Function 



Default 
Syntax 



Use this switch to select only those files 

that match the :f iles= switch and fall within 

the specified size range (in Kbytes) . 

Selects all files that match file selection 

criteria without regard to file size. 

Type :filesiz^ followed by a valid range 

specification. 



Use this switch to hibernate all other 
processes on the system while def raa is 
running. Use this switch only when defrag 
cannot allocate the device, that is, when 
other processes have files open on the device. 
Note that if defrag is able to allocate the 
device, no processes will be hibernated, even 
if the :hibernate switch is specified. 
:nohibernate; i.e. defrag tries to allocate 
the device and does not hibernate processes. 
Type :hibernate to cause all process to be 
hibernated while defrag is running. 



:mod 



Function Use this switch to specify that the 
modification date is to be used in all date 
and time considerations by the :before= or 
:since= switches. 

Default :nomod; i.e. the creation date is used in all 
date and time considerations by the :before= 
or :since= switches. 

^ntax Type anod to use the modification date instead 

of the creation date. 
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: names 



Function Use this switch to suppress the full filename 

line of the :verbose status messages. 
Default :names; i.e. if the :verbose messages are 

being output, also output the full filename on 

the next line. 
Syntax Type :nonames to suppress the lookup and 

output of filenames as part of the verbose 

output. 



: pause 



Function 



Default 
Syntax 



Use this switch to stop the display after each 
screen of information. The user can then 
press [RETRN] to advance one line, or any 
other character to advance to the next screen. 
The value specified to the option command. 
Type : pause or : no pa use to override the 
default. 



:since= 



Function Use this switch to select only those files 
that match the :files= switch and were 
created/modified since the specified date and 
time. 

Default Selects all files that match the :files= 
switch. 

Syntax Type :since= followed by a date and/or time in 

in the standard date and time syntax. 



: stats 



Function Use this switch to request that various 
statistics be displayed at the completion of 
defraa . Note that if statistics are 

requested, additional execution time to 
prepare the statistics will be required. 

Default mostats; i.e. no statistics are displayed. 

Syntax Type : stats to request a statistics display 

upon completion of defrag . 



:typeselect= Function 

Default 
Syntax 



Use this switch to select only those files 

that match the :files= switch and are of the 

given file type. 

Selects all files that match file selection 

criteria without regard to file type. 

Type :typeselect= followed by a list of valid 

file-type specifications. 
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:uic= 



Function Use this switch to select only those files 

that match the :f iles= switch and are owned by 

the specified list of users. 
Default Selects all files that match file selection 

criteria without regard to the owner of the 

files. 
Syntax Type :uic= followed by a list of UICs or 

user names. 



•.verbose 



Function Use this switch to request more status 
information while defraa is executing. If 
specified, defraa will output a message for 
each file that is currently being operated on, 
specifying the operation taking place and the 
FCB and sequence number of the file. 

Default moverbose; i.e. no progressive status 
information will be output. 

Syntax Type rverbose to request log messages for 

every file moved. 



:verify 



Function Use this switch to verify the correctness of 
the KSAM files built by defrag before 
continuing execution of the defraa process. 
If specified, defraa will output a message for 
each bad sector encountered on the disk, and 
also a message for any sectors that are not 
correctly accounted for by the KSAM files. 

Default :verify; i.e. verify the KSAM files. 

Syntax Type mover ify to suppress the verify 

procedure. 
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ExampLes 



> defrag _6c0 



This command will reorganize the file system on device _DC0. The 
following kind of report is displayed on the terminal: 



SYSTEM __NODE_TT0 14-Apr-1986 13:39:11.00 
DEFRA3 beginning on _DC0 

Building free sectors KSAM file. 
Building sector usage KSAM file. 
_DC0/ROOTDIR/FCB.SYS is contiguous 
_DC0/ROOTDII^PCBBrrMAP.SYS is contiguous 
_DC0/RDOTDIR/RDaTDIR.DIR being made contiguous 
Checking directory files 
Checking image files 
Checking remaining files 
Writing out bitmaps 

SYSTEM NODE_TT0 14-Apr-1986 14:48:31.31 

DEFRAG finished on DC0 



> defrag _6c0 :hibernate "seme message" :nobell 

This command will reorganize the file system on device _DC0 the same as 
the first exampLe, except that the following message, without a bell, 
will be sent to all users on the system when defrag is beginning: 



SYSTEM NODE_TT0 14-Apr-1986 13:45:34.23 

DEFRPG beginning on _DC0 
some message 



If defrag is unsuccessful at allocating the device, it attempts to 
hibernate all other processes on the system. When defrag finishes, it 
awakens all the processes that were hibernated. Note that even though 
the :hibernate switch is specified, processes are not hibernated unless 
the device cannot be allocated. A device can be allocated if it is not 
already allocated, and if there are no open files on the device. 
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> defrag _dc0 : stats rnobroadcast 

This command will reorganize the file system on device 
following kind of report is displayed on the terminal: 

Building free sectors KSAM file. 
Building sector usage KSAM file. 
_DC0/ROOTDIR/FCB.SYS is contiguous 
JX0/ITOTDIE/FCBBITMAP.SYS is contiguous 
_IX:0/ROarDIR/ROarDIR.DIR being made contiguous 
Checking directory files 
Checking image files 
Checking remaining files 
Writing out bitmaps 
Preparing statistics 



JX0 . The 



** DEFRPC Statistics ** 



** BEFORE ** 

* Extent size * 

1 sect 883 

2 to 5 sects 2 

6 to 20 sects 

21 to 40 sects 

over 40 sects 

* Number of extents * 



1 Xtnt 

2 to 10 Xtnts 

11 to 30 Xtnts 

31 to 70 Xtnts 

over 70 Xtnts 

Total extents 
Largest # extents 
Largest extent 
Avg # of extents 
FCBs - Free = 
Number files moved = 
Total fcb reads = 



6 
195 
1 
1 
2 



100% 



0% 



4% 
95% 



1% 



885 

159 

4 

4 

19, Primary 



2 to 



** AFTER ** 
Extent size 
sect 
sects 



6 to 20 sects 

21 to 40 sects 

over 40 sects 



* 

3 

179 

17 



1% 
90% 



1% 



* Number of extents * 

1 Xtnt 205 100% 

2 to 10 Xtnts 0% 

11 to 30 Xtnts 0% 

31 to 70 Xtnts 0% 

over 70 Xtnts 0% 



Total extents 

Largest # extents 

Largest extent 

Avg # of extents 

205, Secondary = 



202 
1 

159 
1 





274, Number sectors moved = 
1825, Total fcb writes = 



1543 



784 



Before defrag starts the disk reorganization, it reads through the 
FCB. SYS file and determines the usage of every sector on the disk. While 
it is doing this, it builds the statistics for the "Before" section of 
the statistics display. IXiring execution of defrag , it keeps statistics 
on the number of files and sectors moved and the number of reads and 
writes of the FCB. SYS file. If statistics are requested, then after the 
disk reorganization is completed, defrag reads though the FCB. SYS file 
once again for the purpose of gathering data for the "After" section of 
the statistics display. If the FCB. SYS file is very large, this may take 
a significant amount of time. 
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> defrag _ dcfl :f ile^_dc0/nydir/* rnobroadcast 



This command will reorganize the file system on device __DC0. The files in 
the directory MYDIR will be processed immediately after the main file 
system files (FCB.SYS, FCBBITMAP.SYS, BrTMAP.SYS and ROOTDIR.DIR) . This 
will make the files in the directory MYDIR the closest files to the 
center of the disk and the PCB file, so that the seek time for these 
files will be very small, and the response when accessing these files 
will be the best possible. The following kind of report is displayed on 
the terminal : 

Building free sectors KSAM file. 
Building sector usage KSAM file. 
_DC0/ROOTDIR/FCB.SYS is contiguous 
_DC0/RDOTDIli/FCBBITMAP.SYS is contiguous 
_DC0/ROOODIR/ ROOTDIR.DIR being made contiguous 
Checking User specified files 
Checking directory files 
Checking image files 
Checking remaining files 



> defrag _df0 : verbose : stats rnobroadcast 

This command will reorganize the file system on device _DF0. The verbose 
switch enables a file-by-file progress report to be output to the 
terminal. The following kind of report is displayed: 

Free Space on JDF0 is 28% 

Building free sectors KSAM file. 

Building sector usage KSAM file. 
****** verifying KSAM files 

_DC0/POCTDIR/FCB.SYS being made contiguous 
****** loving extent 0,5 of _DF0//#212.212 

_DF0/ROOTDIR/SECTORJSE. EAT. 1 
****** loving extent 0,9 of _DF0//#109.109 

_DF0/TEST3/DSTAT. HLP. 1 



****** Moving FCB.SYS to target location 

JDF0/ROOTDIR/FCBBITMAP.SYS being made contiguous 
****** Moving extent 0,1 of _DF0//#2.2 

_DF0/ROOTDIR/FCBBITMAP.SYS.l 
****** Moving file _DF0//#3.3 

_DF 0/ROOTDIP/B TTMAP. SYS . 1 
****** Moving file _DF0//#1.1 

JDF0/ROOTDIP/RCOTDIR. DIR.l 
****** now moving in _DF0//#3.3 

_DF0/ROOTDIP/BITMAP.SYS.l 
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****** Now moving in _DF0//#2.2 

_DF0/KX?TDIR/FCBB ITMAP. SYS .1 

_DF0/ROOTDIR/KDOTDIR.DIR being made contiguous 
****** Moving extent ,2 of JDF0//#100 .100 

_DF0/TEST1/DUMP. HLP. 1 
****** Now moving in _DF0//#1 .1 

_DF0/ROOTDIR/ RCOTDIR. DIR. 1 
****** Condensing extents for _DF0//#203.206 

_DF0/ROarDIR/DEPRA3. PAS.l 
****** Condensing extents for _DF0//#4.4 

_DF0/ROCTDIR/TEST1 .DIR.l 



****** Condensing extents for _DF0//#5.5 

_DF0/ROOTDIPy/TEST2. DIR.l 

Checking User specified files 
****** Attempting to make space for _DF0//#203.206 

JDF0/MYDIR/DATSBASE. DAT. 1 
****** Moving file _DF0//#138.138 

_DF0/TEST3/FSTAT. HLP. 1 
****** Moving file _DF0//#136 .136 

_DF0/TEST2/FSTAT. HLP. 1 



****** Ncw moving in _DF0//#203.206 

JDF0/MYDIP/DATABASE. DAT . 1 

Checking directory files 
****** Attempting to make space for _DF0//#4 .4 

_DF0/POOTDIR/TEST1 .DIR.l 
****** Moving extent 0,22 of JDF0//#213.213 

_DF0/ROOTDIR/SECTORJSE. KEY. 1 
****** Moving extent 0,1 of _DF0//#100.100 

_DF0/TEST1/DUMP. HLP. 1 
****** now moving in _DF0//#4.4 

_DF0/ROOTDIR/TEST1 .DIR. 1 
****** Attempting to make space for _DF0//#5.5 

_DF0/ROOTDIR/TEST2 .DIR.l 
****** Moving extent 0,21 of _DF0//#213.213 

_DF0/P£OTDIR/SECTORJSE. KEY. 1 
****** Moving extent 0,2 of _DF0//#101 .101 

_DF0/TEST2/DISPATCH . HLP. 1 
****** Ncw moving in _DF0//#5 .5 

JDF0/PJXTDIR/TEST2 .DIR.l 



Checking image files 
****** Attempting to make space for _DF0//#201.203 



def rag-10 



defrag 



JDF0/MyDIIVMYII«GE.EXE.l 
****** Moving extent 0,2 of _DF0//#112.112 
_PF0/TEST2/DSTAT. HLP.l 



****** Now moving in _DF0//#201.203 

JDF0/MYDIIVMXIMME.EXE.1 

Checking remaining files 
****** Attempting to make space for JDF0//#208.208 

_DF0/RXTDIR/MYFILE. ERN.l 
****** Moving extent 0,1 of _DF0//#99.99 

_DF0/TEST2/DIR. HLP. 1 



****** New moving in _DF0//#208.208 

JDF0/RXTDI!VMyFILE. PRN.l 
****** Attempting to make space for _DF0//#202.205 

J)F0/ROOTDIIV'DISK.CKS.l 
****** Moving extent 0,2 of _DF0//#87.87 

JDF0/TEST1/DIS PATCH. HLP.l 



****** Now moving in _DF0//#202.205 
_DF0/ROOTDI$/DISK. CKS.l 



****** Attempting to make space for _DF0//#196.196 

_DF0/TEST2/PASStfORD. HLP.l 
****** Moving extent 0,6 of _DF0//#215.215 

JDF0/RCOTDIIV'SECrFREE. KEY.l 
****** Now moving in _DF0//#196.196 

_DF0/TEST2/PAS3?ORD.HLP.l 
****** New moving in _DF0//#197.197 

_DF0/ 1 TEST3/PASStfORD. HLP.l 
****** Now moving in _DF0//#199.199 

_DF0/TEST2/PIELIST. HLP.l 
****** Now moving in _DF0//#200.200 

JDF0/TEST1/HJ. HLP.l 

Writing oat bitmaps 

Preparing statistics 
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** DEHtfG Statistics ** 



1 
2 to 5 
6 to 20 sects 
21 to 40 sects 



** BEFORE ** 
* Extent size * 
sect 883 

sects 2 






over 40 sects 







* Nunber of extents * 



1 Xtnt 

2 to 10 Xtnts 

11 to 30 Xtnts 

31 to 70 Xtnts 

over 70 Xtnts 

Total extents 
Largest # extents 
Largest extent 
Avg # of extents 
FCBs - Free = 
Number files moved = 
Total fcb reads = 



6 
195 
1 
1 
2 



100% 



0% 
0% 



3% 
95% 



1% 



885 

159 

4 

4 

19, Primary 



** AFTER ** 

* Extent size * 

1 sect 3 1% 

2 to 5 sects 179 89% 

6 to 20 sects 17 8% 

21 to 40 sects 0% 

over 40 sects 3 1% 

* Number of extents * 

1 Xtnt 205 100% 

2 to 10 Xtnts 0% 

11 to 30 Xtnts 0% 

31 to 70 Xtnts 0% 

over 70 Xtnts 0% 

Total extents 202 

Largest # extents 1 

Largest extent 159 

Avg # of extents 

205 , Secondary = 



274, Number sectors moved = 
1825, Total fcb writes = 



1543 



784 



Using Prompts 



> defrag 

Devicename > __dc0 

This command performs the same function as the first example. 



Notes on Usage 



The defrag utility is very closely related to the file system structure 
of the WMCS. The task that defrag performs is a reorganization of the 
file system on a disk. 

After a disk has been in use for an extended period of time, it is likely 
that large numbers of files have been created and deleted. The process 
of creating and deleting files tends to fragment the free space on a disk 
until there are very few adjacent free sectors on the disk for the next 
file creation. Because the file system will always fulfill a disk 
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allocation request if sectors are available, files are scattered randomly 
across the disk. However, since a typical file does not reside in 
contiguous sectors on the disk, several disk seeks are required when the 
file needs to be accessed. This causes the total disk throughput to 
decrease, since extra time is spent seeking for sectors, rather than just 
having to read consecutive sectors from the disk. 

Disk performance is especially critical when trying to maintain streaming 
operations on a tape drive with data from disk. Given the tape 
controllers and drives that WICAT Systems currently has available when 
doing a backup of the disk, if the disk has to seek to more than the next 
track on the disk, the streaming effect will cease because data were not 
supplied to the tape in time to maintain streaming. 

The defrag utility performs the function of rearranging the sectors used 
by the various files on the disk to make all the sectors used by each 
file on the disk as contiguous as possible, and as a by-product, 
consolidating the free sectors on the disk into two large blocks near the 
front and end of the disk, so that future file creation may have large 
contiguous groups of sectors available for them. 

In order to successfully execute defrag , there are several conditions 
that must be met. First, the process initiating defrag must have the 
appropriate access to the disk. Since defrag is such a powerful program, 
several privileges are required, unless the disk is privately owned by 
the user or process executing defrag . While defrag is running, it must 
insure that no other process can access the disk. Defrag does this by 
either allocating the disk or hibernating all other processes on the 
system. If the process executing defrag owns the disk, and if the disk is 
not the system disk, no special privileges are required because the 
process can allocate the disk. Otherwise the required privileges are 
WOPLD and GROUP access to the disk. If defrag is not installed with 
BYPASS privilege (to let it read and write system control files such as 
FOB. SYS and BITMAP.SYS) , then BYPASS privilege is also required. 

The defrag program also requires a certain amount of free space on the 
disk. The minimum amount of free space required is 15 percent. The 
reason for the free space requirement is that defrag creates some files 
(described below) and also defrag needs to be able to make a backup copy 
of a file before it changes the FGB to point at the new sectors on the 
disk, in order to make it less susceptible to crashes and power failures. 
After defrag builds the KSAM files, it then does another space check. 
This check consists of totaling the sizes of the KSAM files (typically 
6 to 8 percent of the disk) and the two largest files on the disk, which 
may be greater than the previously mentioned 15 percent. If there is not 
enough free space to accommodate this new requirement, defrag will output 
a message to the effect that xxx free sectors are required to 
successfully run defrag on the disk. It will then prompt to see if the 
operator wishes to continue anyway, or quit and attempt to generate more 
free space (by deleting unneeded files, or coding a few large files out 
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to some secondary media) . The defrag program will run in less than the 
optimum amount of free space, but it may not be able to move all the 
files. Note also that due to the organization of any particular disk, 
even if the amount of free space desired is available, defrag may still 
not be able to move all files. 

The defrag program creates two KSAM files to manage the sectors on the 
disk while it is running. The two files are SECTOHJSE. (KEY/EftT) which 
handles all the allocated sectors on the disk, and SECTFREE. (KEY/DAT) 
which handles all the free sectors on the disk. This requires that the 
KSAM class handler be loaded, if it is not already loaded. The ta^o KSAM 
files are deleted by defrag as one of the last tasks it performs, so 
unless the machine crashes during a defrag , these files should never be 
seen. If the machine does happen to crash during defrag , you should run 
recover and delete the KSAM files, then run defrag again. The KSAM files 
are created in the default directory of the user that initiates the 
defrag command. This enables the operator to control where the KSAM 
files are created. If a second disk with sufficient space is available, 
it is usually a good idea to have the KSAM files created on a disk other 
than the target disk. If no other disk is available, defrag will 
correctly run with the KSAM files on the target disk, but will take 
longer, because there are more files to move around to make space for the 
desired files on the disk. 

The defrag program may be terminated before it has run to completion. If 
the operator presses [CTRL] c while defrag is running, it will finish the 
current operation it is performing, write out the bitmaps and terminate. 
This sequence can possibly take some minutes, so there will not be any 
immediate reaction by defrag when [CTRL] c is pressed, but defrag will 
begin the termination process. If defrag is killed by another process, it 
is possible to lose some data, depending on whether it is cbing an _write 
SVC in the operating system or not, so it is recommended that defrag 
never be killed by another process. If necessary, [CTRL] c may be used 
to stop defrag , and then it may be restarted. If nothing was done to 
the disk in the mean time, defrag will start again from the point where 
it was terminated. If the disk has been used, and a file larger that the 
last file being defragmented is created, or one of the defragmented files 
is deleted, defrag will have considerably more work to handle over again, 
as well as the initial setup (up to two hours on a large SMD disk) . 

If defrag runs entirely successfully, and there are no bad sectors on the 
disk, all the files will be contiguous, i.e., contained in one extent. It 
is possible that some files will not be entirely defragmented. There are 
two reasons for this occurrence. The first is that if there are bad 
sectors on the disk, defrag will split a file across the bad sector (s). 
This is essentially the same as if it did defrag successfully. The other 
possibility is if defrag was unable to move some files due to lack of 
space to create the open space for the file. In this case, if defrag is 
run again, it will usually handle these files in the second pass. In 
some cases, it may require several passes to get all files in the optimum 
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defragmented state. 



The defrag program takes a long time to run, considerably longer than 
recover . On a 10-Mfcyte Winchester disk, it takes from approximately 30 
minutes to 3 hours, depending on how full the disk is, how badly the disk 
is fragmented, and the size of the files on the disk. For a 15-Mfcyte 
Winchester, the typical range is about 45 minutes to 5 hours. For a 39- 
Mfcyte Winchester disk, the time range is about 1 hour to 6 hours. For a 
421-Mtyte SMD (Eagle) , the time ranges from 12 hours to 48 hours and even 
longer in some cases. 



Related CXP Commands 



recover Rebuild the file system on a corrupted disk 



def rag-15 



dnapper 



Functional Description 



The dmapper program is a disk utility intended to aid in recovering files 
from a bad disk. This utility is useful for identifying which files and 
locations within those files include particular sectors. It also does 
the inverse mapping identifying which sectors are used by a particular 
file. 



Command Line Syntax 



Mnemonic dnapper 

Required Disk Name or Filename 
parameter 

Switches 

display :header :pause :offset= :sector= 

control :track= 
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Parameters 



Filename 



Function This indicates that a file-to-sector mapping 

is to be displayed for the specified file. 
Default None. 
Syntax Type a valid file designation. 



or 

Disk Name 



Function This indicates that a sector-to-file mapping 

is to be displayed for the specified disk. 
Default None. 
Syntax Type a valid device designation. 



Switches 



rheader 


Function 




Default 




Syntax 


:off set= 


Function 



Default 
Syntax 



Use this switch to specify whether column 

headers should be dispLayed. 

:header (headers are dispLayed) . 

Type rnoheader to suppress column headers. 



Use when a filename has been specified as the 
required parameter. This displays only those 
sectors in which the given offset resides. 
This offset is given in bytes from the start 
of the file. 

All sectors used by a file are displayed. 
Type roffset^ followed by a valid numeric 
range. 



rpause 



Function 



Default 
Syntax 



Use this switch to stop the dispLay after each 
screen of information. The user can then 
press [RETRN] to advance one line, or any 
other character to advance to the next screen. 
The value specified to the option command. 
Type : pause or : no pa use to override the 
default. 
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sector= 



Function 



Default 
Syntax 



Use when a disk name has been specified as the 

required parameter. This displays only those 

files which use sectors in the specified 

range. 

None; sector or track range must be specified. 

Type :sector= followed by a valid numeric 

range. 



:track= 



Function Use when a disk name has been specified as the 
required parameter. This displays only those 
files which use tracks in the specified range. 

Default None; sector or track range must be specified. 

Syntax Type :tracfc= followed by a valid numeric 

range. 



Examples 



> dnapper _ds0/syslib/uaf .dat :affset=200-1500 

This command will display the sectors that are used by the given file at 
the given file offset. The output will be similar to the following: 

Sector map of _NODE_DS0/SYSLIB/UAF.DAT.l 

File Offset Sector # Track # 



00000000 292702 11708 
00000400 292703 11708 

Note that the file offset data is displayed in hexadecimal form on sector 
boundaries. 
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> dnapper _ds0 :sector*15 :track=346 

This command will dispLay the files that use the given sector and the 
given track. The output will be like this: 

File map of NODE DS0 

Sector # Track # File Cffset File 



15 





00000000 


NODE. 


8650 


346 


00000800 


__NODE_ 


8651 


346 


00000C00 


NODE. 


8652 


346 


00001000 


__NODE. 


8653 


346 


00001400 


NODE. 


8654 


346 


00001800 


__NODE. 


8655 


346 


00001C00 


NODE. 


8656 


346 


00002000 


—NODE. 


8657 


346 


00002400 


NODE 


8658 


346 


00002800 


__NODE. 


8659 


346 


00002C00 


NODE. 


8660 


346 


00003000 


__NODE, 


8661 


346 


00003400 


NODE 


8662 


346 


00003800 


__NODE. 


8663 


346 


00003C00 


node" 


8664 


346 


00004000 


__NODE, 


8665 


346 


00004400 


NODE 


8666 


346 


00004800 


_NODE_ 


8667 


346 


00004C00 


NODE 


8668 


346 


00005000 


__NODE_ 


8669 


346 


00005400 


NODE 


8670 


346 


00005800 


__NODE, 


8671 


346 


00005C00 


NODE 


8672 


346 


00006000 


_ -NODE. 


8673 


346 


00006400 


NODE, 


8674 


346 


00006800 


NODE 



DS0/SOMEWHERE/TEST1 . EAT .3 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .DAT. 1 
.DS0/DIR1 . DIR2 . DIR3/TEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT. 1 
DS0/DIR1 . DIR2 . DIR3 AEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT.l 
DS0/DIR1 . DIE2 . DIR3/TEST2 . EAT .1 
DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT. 1 
DS0/DIR1 . DIE2 . DIR3/TEST2 . EAT .1 
JDS0/DIR1 .DIR2 .DIR3/TEST2 .EAT.l 
DS0/DIR1 . DIK2 . DIR3/TEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT.l 
DS0/DIRL . DIR2 . DIR3/TEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT.l 
DS0/DIE1 . DIR2 . DIR3 AEST2 . EAT .1 
DS0/DIR1 .DIR2 .DIR3/TEST2 .IAT.1 
DS0/DIR1 . DIR2 . DIR3/TEST2 . EAT .1 
JDS0/DIR1 .DIR2 .DIR3/TEST2 .EAT. 1 
.DS0/DIRL . DIE2 . DIR3/TEST2 . EAT .1 
_DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT. 1 
.DS0/DIRL . DIE2 . DIR3 AEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT.l 
DS0/DIE1 . DIE2 . DIR3/TEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .EAT. 1 
DS0/DIR1 . DIP2 . DIR3/TEST2 . EAT .1 
.DS0/DIR1 .DIR2 .DIR3/TEST2 .DAT. 1 



Using Prompts 



> dmapper 

File or Disk > _ds0/syslib/uaf .dat :offset=200-1500 

This performs the same function as the first example. 
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Notes on Usage 



The dmapper program accepts a disk name or filename as a parameter and 
determines the mapping function to be performed. If a disk name is 
specified, dmapper will perform a sector-to-file mapping. If a filename 
is specified, dmapper will perform a file-to-sector mapping. 



Related CIP Commands 



chkd 



Check a disk for bad sectors 
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Functional Description 



This utility is typically used to compile and maintain programs by using 
a make control file. The make control file specifies the dependencies of 
the program on source files r header files, include files, object files, 
library files, etc. If any of the files upon which the end program 
depends has changed since the end program was last built, make will 
automatically rebuild the necessary pieces and produce the end program. 
Using the make control file, this utility will compare the creation date 
of a primary file to a list of secondary files. If one or more of the 
secondary files has a creation date later than the primary file, all 
following lines that begin with a vertical line, I , will be executed. 
These lines may be any valid CXP command line. If none of the secondary 
files has a creation date later than the primary file, all following 
lines that begin with I will be skipped. If an error is returned from an 
executing program, make will terminate. 



Command Line Syntax 



Mnanonic make 

Optional Make Control File 

parameters Parameter 1-10 

Switches :comments rpause rverbose 



make-1 



make 



Parameters 



Make Oontrol File Function 



Default 



Syntax 



This defines the name of the make oontrol 
file which describes what make is supposed 
to do. 

If no file is specif ied f it will use a file 
called MAKE.MAK in the current directory. 
Type a valid file designation. If no 
extension is specified, an extension of 
• MAK will be appended to the name. 



Parameter 1-10 



Function Up to ten parameters may be passed on the 

command line cbwn to the make control file. 

These parameters will, be assigned to the 

logical names pi, p2 , p3, ... pN 

respectively. 
Default None of these logical names will be 

defined. 
Syntax Type any valid command-line parameter. 

Note that items inside double quotes will 

be taken as one parameter. 



Switches 



: comments 


Function 




Default 




Syntax 


rpause 


Function 



Default 
Syntax 



Use this switch to enable the display of 
comment lines while make is executing. 
: comments (comments are displayed) 
Type :noooaments to suppress the display of 
comment lines during execution. 



Use this switch to stop the display after 
each screen of information. The user can 
then press [RETRN] to advance one line, or 
any other character to advance to the next 
screen. 

The value specified by the option command. 
Type : pause or :no pause to override the 
default. 
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rverbose Function Use this switch to specif/ whether make 

should display the primary/secondary file 
comparison information. 
Default :noverbose (do not dispLay the information) 
Syntax Type : verbose to display the file 

comparison information. 



Examples 



All the examples use the following make control file. 

test.w test.c test.h 

sys$disk/sy sincl . sys/sy serr . h 
sys $disk/sy sincl . sys/f cbdisp. h 

I compile test.c :noload 'pi' 

testsub.w testsub.c test.h 

I compile testsub.c -.noload 'pi' 

test.exe test.w testsub.w 

! compile test. w, testsub. w 'pi* 



> make 

This command will look for a file called MAKE.MAK in the current 
directory. If this make control file has the contents shewn above, and if 
the user has edited both .C source files since the last time a make was 
performed, then the creation dates for the two .C source files are later 
than the creation dates for each of the ,W files. The output from the 
above command would be: 

> compile test.c : noload 

node_ds0/users. test/test. c.0 : 

> compile testsub.c moload 

node_ds0/user s. test/testsub. c.0: 

> compile test.w, testsub.w 
test. exe : 

Note that because the two .C files were recompiled, when it came time to 
compare the dates between the .EXE and the ,W files, the .W files had a 
later creation date. This caused the .W files to be linked, thus 
creating a new .EXE file. 
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> make :verbose "rverbose" 

With the same situation as in the above example, the output of this 
command would be: 

test.w -1986-04-25 22:39:15.22 

test.c 1986-04-25 22:40:25.78 * 

test.h 1986-04-24 16:36:18.27 

sys$disk/sysincl.sys/syserr.h 1986-04-01 00:00:00.00 

sys$disk/sysind.sys/fcbdisp.h 1986-03-18 10:27:17.71 

> compile test.c moload :verbose 
node_ds0/user s. test/test . c. : 

sy s$disk/ucc/cpp. exe >sy s$tmp/sy stmp/CCCP2c2f a node_ds0/user s. test/test . c. I 

sy s $disk/ucc/ccom. exe sy s $tmp/sy stmp/CCCP2c2f a sy s $tmp/sy stmp/CCCQ2c2f b 
sys$disk/sysexe.sgs/al ib2.exe -o sys$tmp/systmp/CCCR2c2fc sys$tmp/systmp/CCO 
sys$disk/sysexe.sgs/wimac.exe -0 -o test.w sys$tmp/systaip/CCCR2c2fc 
testsub.w -1986-04-25 22:39:21.78 

testsub.c 1986-04-25 22:40:25.78 * 

test.h 1986-04-24 16:36:18.27 

> compile testsub.c moload :verbose 
node_ds0/user s. test/testsub. c. : 

sys$disk/ucc/cpp. exe >sys$tmp/systmp/CCCP2c34a node_ds0/users. test/testsub 

sys $disk/ucc/ccom. exe sys$tmp/systmp/CCCP2c34a sys$tmp/systmp/CCCQ2c34b 
sys$disk/sysexe.sgs/al ib2.exe -o sys$tmp/systmp/CCCR2c34c sys$tmp/systmp /r LCI 
sys$disk/sysexe.sgs/wimac.exe -0 -o testsub.w sys$tmp/systmp/CCCR2c34c 
test. exe -1986-04-25 22:39:31.65 

test.w 1986-04-25 22:40:58.58 * 

testsub.w 1986-04-25 22:41:05.70 * 

> compile test.w, testsub.w :verbose 
test. exe: 

sys$disk/sysexe.sgs/ll. exe <sys$tmp/systmp/CCCP2c39a 

Note that secondary files whose dates are later than the primary file are 
flagged with an asterisk. 
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If the same canmand as in the previous example were executed again 
without changing any of the files, this would be the output: 

test.w -1986-04-24 16:53:28.93 

test.c 1986-04-24 16:53:14.38 

test.h 1986-04-24 16:36:18.27 

sys$disk/sysincl.sys/syserr.h 1986-04-01 00:00:00.00 

sys$disk/sysincl.sys/fcbdisp.h 1986-03-18 10:27:17.71 

testsub.w -1986-04-24 16:53:38.48 

testsub.c 1986-04-24 16:53:14.38 

test.h 1986-04-24 16:36:18.27 

test.exe -1986-04-24 16:53:55.58 

test.w 1986-04-24 16:53:28.93 

testsub.w 1986-04-24 16:53:38.48 



> make test 

This will look for a file called TEST.MAK in the current directory. 

Using Prompts 
None. 

Notes on Usage 



A make control file consists of one or more compilation units. A 
compilation unit consists of a primary file designation followed by a 
list of one or more secondary file designations (there is no limit to hew 
many secondary files may be specified) . This is followed by one or more 
execution lines (each beginning with I ) that are to be executed if any of 
the secondary files have a creation date later than the primary file or 
if the primary file does not exist. There is no limit as to how many 
execution lines there may be. 

Make control files have the following syntax: 

- Lines beginning with the number sign, #, are comments to be 
displayed if the :ccmments switch is set (this is the default). 
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- Lines beginning with the exclamation point, !, are comments which 
are never displayed. 

- Gonsecutive lines beginning with the vertical line, I , are commands 
to be executed if the preceeding primary file is not as recent as 
one or more of the associated secondary files, or if the primary 
file does not exist. Execution lines may be continued by a 
backslash, \/ as the last character of the line. Anything that can 
be placed in a command file may be placed on these lines. Comment 
lines may be placed in the middle of a list of execution lines 
without affecting the execution flow. 

- Lines beginning with the at sign, @, are nested make control files. 
The default directory will be changed to the path of the given 
make control file. Execution will then continue with the new make 
control file. When processing of the sub -make control file is 
completed, the default will be returned back to where it was and 
processing will continue with the original make control file. Sub- 
make control files may be nested as many levels as is desired. 

- Lines beginning otherwise are filenames. The first file is the 
primary file; all others are secondary files. If the primary file 
does not exist, then the associated compilation unit will be 
executed. If a secondary file cbes not exist, an error will be 
reported and make will terminate. Any combination of one or more 
tabs, spaces, or newlines are filename separators. 

A compilation unit is terminated by encountering one of the following: 

- Another compilation unit (lines that no longer begin with I) . 

- A sub -make control file specification. 

- The end of the make control file. 

Blank lines may be inserted anywhere inside a make control file without 
affecting the flow of compilation units. 

Use TOUCH (this is a logical name in LOCALUP. (DM) to change a secondary 
file's creation date to the current date and time. With this a user can 
force a regeneration of a program without having to edit the files. 

Any command that may appear in a command file may be placed on an 
execution line. Elow control commands (goto , for , while , loop , call , if) 
may not cross compilation units. 

If an abort reason other than zero is returned from an execution line 
process, then make will terminate immediately. 
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We wish to caution you about referencing files on different network nodes 
with make . Since each machine has its own local time definition and 
since they probably will not exactly agree, make 's time comparisons 
between the primary and secondary files may not be valid and prograns may 
be incorrectly built. 

Ebr an example of a make file, see SYSSDISK/SY5DSR/DISKCF3.MAK. 



Related CIP Commands 



cip Execute a copy of a P. EXE 
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Chapter 2 
QP Command Language 



The WMCS User's Reference Manual describes the Command Interpreter 
Program (CEP) . 

This chapter describes the command language that has teen added to the 
CTP. To use this language, you must understand the information in the 
WMCS User's Reference Manual as well as the information in this chapter. 

This chapter is divided into two parts: 

Information on general features of the language 

A dictionary of statements available in the new language 

Features of the Language 

This section describes features and capabilities of the command language 
that are now part of the CI P. 



The CLP has a new class of variables called symbols. Symbols' differ 
from logical names in that symbols are local to the CTP and are 
maintained inside the CXP. All symbols are maintained in string 
form. Logical names, on the other hand, are maintained inside the 
operating system and an SVC is executed every time a user accesses a 
logical name. 

A symbol must begin with an alpha character and can contain any 
printable character other than expression operators (described under 
the Expressions heading in this chapter). All symbol names are 
mapped to upper case inside the CI P. A symbol array is defined by a 
symbol name, followed immediately by square brackets, with an 
expression inside the square brackets. The value of the expression 
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is substituted for the expression. Symbol arrays can be nested 
within each other. 

This is a list of sample symbol names: 

a 

this$is$a$very $long$symbol frame 

test_symbol 

test [1] 

test[a*25] 

test[idx[x-3]+4] 

The following subheads contain information on the four types of 
symbols available in the a P. 

Note that the four groups of symbols are maintained in separate 
lists and that names can be duplicated across these lists without 
conflicts. In other words , you can have a symbol in one list whose 
name matches a symbol in another list and the CIP will not confuse 
the two symbols. 



Symbol 



These variables contain values that can be used in expressions. 
This is the most commonly used type of symbol. 



Filelun Symbol 



These symbols are used with the open , crfile , openpipe , close , read . 
write , and writeln statements (described later in this chapter) . 
They contain the logical unit number (LUN) for a given open file. 
These symbols cannot be used in expression evaluation. 

There are three built-in filelun symbols: input, output, and error. 
These can be used in any of the statements that are part of the 
command language. 



Label Symbol 



These symbols are defined by the label statements (described later 
in this chapter) and are referenced by goto and .on statements. These 
symbols define a specific location in a command file. These symbols 
cannot be used in expression evaluation. 
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Procedure Symbol 



These symbols are defined by the procedure statement (described 
later in this chapter) and are referenced by the call statement. 
These symbols define a subroutine in a command file. These symbols 
cannot be used in expression evaluation. 



The QP now has the ability to evaluate expressions. These are the 
operators and the meaning of each: 

Operator Function 

+ Binary addition 

Binary subtraction and unary minus 

* Binary multiplication 

/ Binary division 

mod Binary modulo 

not Unary logical not 

It Logical binary less than 

le Logical binary less than or equal 

gt Logical binary greater than 

ge Logical binary greater than or equal 

eq Logical binary equal 

ne Logical binary not equal 

Its Logical string less than 

les Logical string less than or equal 

gts Logical string greater than 

ges Logical string greater than or equal 

eqs Logical string equal 

nes Logical string not equal 

and Logical and 

or Logical .o_r_ 

() Parenthesis to control the order of evaluation 

The following list illustrates the precedence of the operators. 
(Entries on the same line have equal precedence and are evaluated 
left to right.) 





- not 

* / mod 

+ - 

It le gt ge Its les gts ges 

eq ne eqs nes 

and or 



(unary operators] 



(comparison operators) 
(comparison operators) 
(logical) 
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Comparison operators have two forms: 

The operators without the trailing "s" do binary comparisons, 
converting the strings to binary and then comparing them. 

The operators with the trailing "s" do string comparisons, 
comparing the actual strings with each other. 

All operators except the string comparison operators convert the 
symbol strings to binary before the operation is performed. 

The specified operators work on four types of operands: 

Numeric literals : These are operands that begin with a nimber, 
a percent sign, %, or a dollar sign. If the operand begins 
with a number or a percent sign, the result is a decimal 
number. If the operand begins with a dollar sign, the result 
is a hexadecimal number. 

String literals : These are arbitrary strings surrounded by 
double quotation marks. 

gymfrols 
Symbol arrays 

Spaces and tabs between the operators and operands are insignificant 
except for those operators that are strings (not, mod, and, or, and 
the comparison operators) . They must have at least one space or tab 
character between themselves and symbols. 

The result of a comparison operation is a binary 1 if the comparison 
is true and a binary if the comparison is false. The not operator 
changes a binary to 1 or a binary 1 to 0. 

There are two predefined symbol names built into the CIP: true 
(which has a value of 1) and false (which has a value of 0) . 

Expressions can be arbitrarily complex, and there is no limit to how 
deeply they can be nested. 

Note that an expression need not contain an operator; it can simply 
be one of the operands. 
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These are examples of how to use the operators just described. 

let a = 10 let b = "This is a test" 

These commands assign to the symbols A and B the values of 10 
and "This is a test" respectively. Note that numeric and 
string literals are acceptable expressions. 

let a = 20*tmpHanp£/3 

This command assigns the value of the given expression to 
symbol A. Note that the multiplication and division are done 
before the addition because of operator precedence. 

if a gt 20 and b eqs ■/" or c ne 3 

This command performs all of the comparison operations before 
the and and or operations occur. Note that you can intermix 
string and binary comparisons. 

intrinsic functions 

The CEP has several intrinsic functions. These functions can be 
placed anywhere on any command line. When the command line is 
parsed, the value of the function is substituted for the function 
call. All intrinsic functions begin with a percent sign, %, and 
are followed by the name of the intrinsic. The name is followed by 
an opening parenthesis, then all applicable parameters, and then a 
closing parenthesis. Logical name translations can be used as 
paraneters to intrinsics. Intrinsic functions can be nested within 
each other to any level. All intrinsic parameters are treated as 
expressions and are evaluated. (Read the description of the let 
statement for a definition of expressions.) 

These are the functions intrinsic to the dP: 

%copy ( expr ession-1 , expression-2 [ , expr ession-3 ] ) 

Copy the number of characters specified by expression-3 from 
expression-1. Start the copy at the position specified by 
expression-2 (the first character of the string is position 1) . 
If expression-2 is beyond the end of the string, an error will 
be reported. If expression-3 is missing, copy from the 
specified position to the end of the string. 
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%createtime( filelun symbol or expression) 

Substitute the creation date and time of the specified file. 
If a filelun symbol is specified, the creation date and time of 
the specified open file is used. If an expression is 
specified, it is evaluated and the result is used as a file to 
open. The creation date and time of this file are used. The 
file is then closed. 

%date() 

Substitute the current day, month, and year. 

%default() 

Substitute the path for the default directory, in the following 
form: 

node_dev ice/directory/ . 

%delete (expression-1 , expression-2 [ , expression-3] ) 

Delete the number of characters specified by expression-3 from 
expression-1 . Start the deletion at the position specified by 
expression-2 (the first character of the string is position 1) . 
If expression-2 is beyond the end of the string, an error will 
be reported. If expression-3 is missing, delete from the 
specified position to the end of the string. 

%device( filelun symbol or expression) 

Substitute the devicename part of the specified filename. If a 
filelun symbol is specified, this will use the complete name of 
the specified open file. If an expression is specified, it 
evaluates the expression and uses the result as a filename. 

%directory( filelun symbol or expression [ f dirnum.]) 

Substitute the directory name part of the specified file 
designation. If a filelun symbol is specified, the function 
uses the complete name of the open file. If an expression is 
specified, it evaluates the expression and uses the result as a 
filename. If dirnum is zero or unspecified, the entire 
directory path is substituted. If dirnum is negative, the left 
most dirnum directories are substituted. If dirnum is 
positive, the rightmost dirnum directories are substituted. 
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%eval (expression) 



Substitute the value of the given expression after it has been 
evaluated. This is used to force the evaluation of symbols and 
expressions anywhere on a command line, 

%extension(FILHflN SDBCL or EXHIESSICN) 

Substitute the extension part of the specified file 
designation. If a filelun symbol is specified, this function 
uses the complete name of the open file. If an expression is 
specified, it evaluates the expression and uses the result as a 
filename. 

%file( filelun. symbol or expression) 

Substitute the filename part of the specified file designation. 
If a filelun symbol is specified, this function uses the 
complete nane of the open file. If an expression is specified, 
it evaluates the expression and uses the result as a filename. 

%insert (expression-1 , expression-2 , expression-3) 

Substitute the string generated by inserting string expression- 
1 into string expression-2 in front of the character specified 
by the position at expression-3 (the first character of the 
string is position 1) . If expression-3 is beyond the end of 
the string, an error is reported. 

%length(expression) 

Substitute the length of the evaluated string expression. 

%lower (expression) 

Substitute the evaluated string expression mapped to lower 
case. 

%mDdtime( filelun symbol or expression) 

Substitute the modification date and time of the specified 
file. If a filelun symbol is specified, the modification date 
and time of the specified open file are used. If an expression 
is specified, it is evaluated and the result is used as a file 
to open. The modification date and time of this file are used. 
The file is then closed. 
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CIP Gommand Language 



%name(f ilelun symbol or expression) 

Substitute the complete filename of the specified file. If a 
f ilelun symbol is specified, this will use the complete name of 
the given open file. If an expression is specified, it 
evaluates the expression and uses the result as a filename to 
open. If this succeeds, the complete filename is used. The 
file is then closed. 

%node(f ilelun symbol or expression) 

Substitute the node name part of the specified filename. If a 
f ilelun symbol is specified, this uses the complete name of the 
given open file. If an expression is specified, it evaluates 
the expression and uses the result as a filename. 

%numparans() 

Substitute the number of parameters that were specified on the 
command line to the CIP. This is valid only inside of command 
files. 

%pos (expression-1 , expression-2) 

Substitute the position of expression-1 in expression-2. A 
value of zero is given if expression-1 is not found in 
expression-2. 

%time() 

Substitute the current system time — hours, minutes, seconds, 
and ticks. 

%trans (expression) 

Substitute the logical name translation of the evaluated string 
expression. If there is no translation, a null string is 
given. 

%upper (expression) 

Substitute the evaluated string expression mapped to upper 
case. 



2-8 



CXP Command Language 

%version(filelun symbol or expression) 

Substitute the version part of the specified filename. If a 
f ilelun symbol is specified, this uses the complete name of the 
given open file. If an expression is specified, it evaluates 
the expression and uses the result as a filename. 

It is very important to realize that intrinsics do string 
substitution at the time the command line is parsed. Inasmuch as 
all parameters to the intrinsics are taken as expressions and are 
evaluated, you will usually need to put double quotation marks 
around the value of an intrinsic so that the output is taken as a 
string literal. If you do not, the output is taken as a symbol and 
is reevaluated. 

The following are examples of intrinsic functions: 

let a = a %de£ault() H 

Assigns the default directory to symbol a. 

let b - "%lower("%directory("%default()" f l)")" 

Assigns to symbol b the right most subdirectory of the default 
directory mapped to lower case. 

let c = ■_%nodB("%defaiilt()")/%directoiy("%de£ault()")/" 

Assigns to symbol c the concatenation of " " with the default 

node name followed by a slash, followed by the default 
directory, followed by a slash. 

let d = ■%delete("%time()" / 6)> ■ 

Assigns to symbol d the first five characters of the current 
time (hours and minutes) followed by a right angle-bracket and 
a space. The time part is done by deleting from character six 
to the end of the string. 
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let e = ■%I^aBle(■ , pl , ■)■ 

let f = "%ooHr(e r %pos(VF"%ooEy(e r %pos(Vre)+l)")-^pos(Vfe)+l) 

This example assigns to symbol e the pathname of the given 
parameter. It then assigns to the symbol f the filename, 
extension, and version portion of the pathname. This is done 
by locating the two slashes and getting the portion of the 
string immediately after the second slash. The above example 
can also be accomplished by executing the following line: 

let f = "%file(e) ,%extension(e) Aversion (e) " 

for i=l,i le %nunparans() ,i=i+l 

writeln "P%eval(i) = %trans("p%eval(i)")" 
endfor 

This for loop displays the value of each parameter that was 
specified on the command line. If these commands are in a 
command file called FOR. (DM, and if the following commands were 
executed, the following output would result: 

@for this is "a test" of this 

Pi = this 
P2 = is 
P3 = a test 
P4 = of 
F5 = this 

Flow control constructs (if, for, loop, while , etc.) can also be 
entered interactively on the command line. If a starting flow 
control construct is entered, the CIP changes the current prompt to 
that construct' s name followed by a number. The number is the 
current nesting level. Any command can be entered while in this 
state. If another starting flow control construct is entered (it 
can be the same one or a different one) , the prompt is changed to 
that construct' s name and the nesting level number is incremented. 
Note that all commands entered in this mode are not executed, but 
are saved for later execution. When an ending flow control contruct 
is entered (endif, endfor, endloop, endwhile, etc.), the nesting 
level is decremented and the command line prompt is changed back to 
the previous nesting construct' s name. When the nesting level goes 
back to zero (the initial state, before the first starting flow 
control construct was entered) , the CIP starts executing the 
commands beginning with the first flow control construct entered. 
When the flow control construct terminates, the user's prompt is 
changed back to its original state. 

Multiple commands can be entered on the same line separated by 
semicolons (including loop control constructs). 
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CIP Command Language 



Dictionary of CIP Statements 



The WMCS User's Reference Manual contains descriptions for each of the 
commands constituting the CEP. 

The descriptions in this section are for the QP statements that have 
been added to the QP as part of the command language. Most of these 
statements are new and are intended to be used almost exclusively in 
command files. Nevertheless, the commands marked with an asterisk existed 
previously and were described in the WMCS User's Reference Manual . Those 
commands have been enhanced for use with the new CIP command language. 

call for log* pause scrnpos 

cd* goto loop pd symbol 

close if on procedure termopen 

cmdst* label open read while 

crfile let openpipe return write 

echo lineclr option* scrnclr writeln 
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call 



Functional Description 



Use this command to call a procedure. The procedure must be defined 
elsewhere within the same command file, either before or after you invoke 
call . Upon return from the called procedure, control returns to the CLP 
statement immediately following the call . 



Gommand Line Syntax 



Mnemonic call 

Required Procedure name 

parameter 



Parameters 



Procedure name Function Required. This parameter defines the name of 

the procedure to be called. 
Default None. 
Syntax Type a valid procedure symbol. 



Switches 



None. 



call -1 



call 



Examples 



call getjdir 

This command calls a procedure named GET_DIR that is defined by a 
procedure command elsewhere in the same QP command file. When GETJDIR 
concludes, control returns to the statement following call . 



Notes on Usage 

You define the functionality of the procedure specified in the call 
statement. 

Calls can be nested to any level and are limited only by available 
memory. 

Recursive calls are allowed. 

No parameters are explicitly passed to the specified procedure; all 
variables used in a command file are global. 

When the CIP encounters endprocedure or return in the spe.cified 
procedure, control is transferred to the statement after call . 

The specified procedure can be defined anywhere in the same command file 
containing the call statement. If the procedure is defined before the 
call statement, the QP transfers control directly to the procedure. If 
the procedure definition appears after the call statement, the CLP 
searches for the definition and then transfers control. (If no 
definition is found, the QP exits the command file and generates a 
diagnostic message.) 

Procedure symbols are distinct from symbols, label symbols, and filelun 
symbols, and can therefore have the same names as symbols of other types. 

Procedure symbols cannot be used in expressions. 



call -2 



call 



Related CIP Commands and Statements 



return Return frcm a procedure 

procedure Define a procedure 
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cd 



Functional Description 



Use this command to change the default directory. 



Command Line Syntax 



Mnemonic cd 

Optional Directory 
parameter 

Switches :log :perm 



larameters 



Directory Function Optional. Use this parameter to specify the 

node, device, or directory that you want as 

your new default directory. 
Default The directory you are in (that is, the 

directory that is already the default) . 
Syntax Use the standard syntax for directory paths. 

Wildcard symbols are not allowed. 
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cd 



Switches 



:log 



:perm 



Function Specifies whether or not log messages are 
displayed ty utilities. (Log messages report 
on what the utility is doing.) 

Default The value specified for the option command. 
(The default for option is :log.) 

Syntax Type :nolog or :log. 

Function Specifies whether or not you want the change 
(specified by the command) to last even after 
execution of the current QP is complete. For 
example, :perm in a command file makes the 
change specified on that line persist after 
execution of the command file is complete. Used 
with loo, this switch logs you out of all 
nested command files and puts you in your last 
(or most recent) interactive CEP. 

Default :noperm 

Syntax Type :perm or :nopexm. 



Examples 



cd 

When you strike [RETRN] after typing the foregoing command, this kind of 
report appears on the screen: 

__BAR1LEB Y_DS0/USERS. PL/ 

The foregoing report tells you what your default directory is. 

cd _dc0/users 

This command changes the default directory to /USERS/, on disk __DC0. The 
following display appears on your screen when you strike [RET1FN] : 

JX0/USERS/ 

This report tells you that _DC0/USERS/ is now the default directory. 
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cd 



cd .march 

This command changes the default directory to /MARCH/, a subdirectory of 
the default directory. (The period preceding "march" tells the CEP that 
/MARCH/ is a subdirectory of the default directory.) Note that this 
command does not change the default device. Were /MARCH/ a subdirectory 
of /USERS/, the following display would appear when you strike [RECRN] : 

_DC0/USERS. MARCH/ 

cd - 

This command moves you to the parent directory of the directory you are 
in. For exampLe, were you in _DC0/USEFS.MARck/, the foregoing command 
would move you to _DC0/USERS/ . 

cd _dc0/users.march/ :perm :nolog 

The :perm switch has meaning only when you use c^ in a command file. For 
exanple, when the execution of a command file ends, the CIP returns you 
to the directory you were in when you executed the file. When you use 
:perm with a c£ command in a command file, the CXP puts you in that 
directory when execution of the command file ends — regardless of where 
you were when you executed the file. (If you use :perm with several cd 
commands in a command file, the CEP puts you in the directory specified 
by the last cd statement that was executed before the end of the ccmmand 
file.) 

The molog switch tells the CEP not to display the report generated by 
cd to tell you what the default is. 



Using Prompts 



None. 



Notes on Usage 

If you type cd on the command line and strike [REHEN] , the designation 
for the default directory appears on the screen. 
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cd 



Related CEP Commands and Statements 



def Display the name of the default device and directory 

crd Create a directory 

pd Change back to your previous default directory 
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dose 



Functional Description 



This command closes the file associated with the given filelun symbol. 
(See the crfile statement for information on assigning the filelun 
symbol.) 



Command Line Syntax 



Mnemonic close 

Required Filelun 
parameter 

Switches :mode= 



Parameters 



Filelun Function Required. The name of the filelun symbol 

associated with the file to be closed. If the 
filelun symbol is undefined, a diagnostic 
message results. 

Default None. 

Syntax Type a filelun symbol. 
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close 



Switches 



:mode= 



Function Specifies the mode to be used when a file (or 
pipe) is created, opened, or closed. 

Default Depends on what you are doing to the file or 
pipe: 



Action 



Default 



Syntax 



File: create 


write 


File: open 


read 


File: close 


none desired 


Pipe: open 


read 



Note that if you type this switch, you must 
also specify the kind of access you want (see 
the list, under syntax, of what you can 
specify) . In other words, if you type :mode= 
and you want read access, you must type read 
as one of the values for this switch even 
though it may be the default. 
Type :mode= followed by any combination of the 
modes listed under the action you want to 
perform. If you specify more than one mode, 
separate the modes by commas. Unique 
abbreviations of the mode names are allowed. 



For example, if you are creating a file, you 
can choose any (as well as any combination) of 
the modes listed under "Create a file", but if 
you are opening a pipe, only four modes are 
available. 

Create a file: 



append nor emote read 

delete notruncfile readLock 

nextfile openif there write 

noreadahead openshared writelock 



zerodelete 



Open a file: 

append 
delete 
nextfile 



noreadahead openshared write 
nor emote read writelock 

notruncfile readLock zerodelete 
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close 



dose a file: 

del ete nodel et e supal 1 del ete 

forcectorite notruncfile zerodelete 

Open a pipe: 

read readLock writelock write 



Examples 



close fnam 

This command closes the file associated with the f ilelun symbol fnam. 

close fnam anode=delete 

This command closes the file associated with the f ilelun symbol fnam. 
After the file is closed, it will be deleted. 



Using Prompts 



None. 



Notes on Usage 



Close is generally used to close a data file from within a command file. 

The status of this operation is assigned to the logical name SYS$RESULT. 

Filelun symbols are distinct from symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 

Filelun symbols cannot be used in expressions. 
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close 



Related QP Canmands and Stat anents 



erf He Create a file and associate a f ilelun with it 

open Open a file and associate a f ilelun with it 

open pipe Open a pipe associated with output frcm a previous command 

read Read from a file 

write Write to a file 

writeln Write a line to a file 
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andst 



Functional Description 



Use this command to manage the list of previous CXP commands entered at a 
user's terminal. 



Command Line 


Syntax 










Mnemonic 
Switches 


cmdst 

: delete 
:restore= 


:full 
:save 


: pa use 
:save= 


: restore 




Parameters 













None. 



Switches 



: delete 



Function Deletes all commands in the current command 

stack. 
Default rnodelete 
Syntax Type : delete to delete all commands from the 

command stack. 
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:full 



: pause 



Function Tells the CIP to display a list of all commands 
entered since the user logged on to the system. 

Default :nofull 

Syntax Type :full to dispLay all commands in the 

command stack, or :nofull to dispLay only the 
top 20 lines from the command stack (the 20 
most recently entered or executed commands) . 

Function Specifies whether or not the command pauses 
after displaying a screenful of information. 

Default The value specified by the option command. 

Syntax Type : pause or : no pause to override the 

default. 



:restore 



Function 



Default 
Syntax 



Tells the CXP whether or not to load the 

command-stack buffer from CTPCMD.STK in your 

home directory. All commands already in the 

command-stack buffer are lost. 

morestore 

Type : restore to load a new command stack from 

a file. 



:restor< 



:save 



:save= 



Function Tells the CEP the file designation for the file 
from which the CEP is to load the ccmmand-stack 
buffer. All commands al ready in the command- 
stack buffer are lost. 

Default Do not load from a saved command stack file. 

Syntax Type :restore= followed by a file designation. 

Function Specifies whether or not the CIP saves the 
current command stack buffer in file GPCMD.STK 
in your home directory. If CEPCMD.STK exists 
already, :save tells the CIP to replace it. 

Default cnosave 

Syntax Type :save to have the CEP save a copy of the 

command-stack buffer, or type rnosave to tell 
the CIP not to save a copy. 

Function Specifies the name of the file to which you 
want the CIP to save the current contents of 
the command-stack buffer. If the specified 
file exists alreacy, the CEP deletes it before 
creating the new file fcy the same name. 

IDefault Do not save the current command stack buffer. 

Syntax Type :save= followed by a file designation. 



cmdst -2 



andst 



Examples 



andst 

This oommand shews either all the commands you have executed or the last 
20 commands you have executed, whichever is the smaller quantity. If 
this is the first command typed after you log on, the following display 
appears : 

> cmdst 

If you have been working in the CEP for several minutes, your display 
would look something like this: 

> mnt _dxl 

> copy *.dat _dxI/rootdir/* 

> cd .work 

> dir 

> co£y *.exe _dxl/*/* :build 

> sp _dxl 

> dmnt _dxl :auto 

> def 

> pu 

> cm 

> stat 

> vew test. pas 

> link test 

> test 

> dstat 

> vew 

> pas test. pas 

> link test 

> test 

> cmdst 

cmdst :full :pause 

This command displays all of the information in the previous example plus 
all commands executed before the 20th command. The : pause switch causes 
the display to pause after each 20 commands. 

cmdst rsasre 

This command will save the current command stack in a file called 
QPCMD.STK in the user's home directory. 
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andst 



andst :restore=sys$disk/users.bcDiedii/iiysa^e.stk 

This command will load the current canmand stack buffer from the file 
SYS^ISK/USERS.HOMEDIK/MYSAVE.STK. The previous contents of the command 
stack buffer are lost. 



Using Prompts 



None. 



Notes on Usage 



The CIP has an internal buffer of 1.5 Kbytes that lets it save between 80 
and 140 of the previously executed commands. When the buffer is full, 
the commands begin scrolling through the buffer, and the oldest commands 
are lost. 



Related CEP Commands and Statements 



None. 



cmdst -4 



crfile 



Functional Description 



This command creates a file and associates it with a f ilelun symbol. 



Command Line Syntax 



Mnemonic 



crfile 



Required 
parameters 

Switches 



Filename 
Filelun 

:f ilei6= 
: protection 5 



:f iletype= 
:uic= 



:mode= 



Parameters 



Filename 


Function 




Default 




Syntax 


Filelun 


Function 




Default 




Syntax 



Required. The name of the file to be created. 

None. 

Type a file designation. 



Required. The name of the filelun symbol to 

be associated with the file to be created. If 

the filelun symbol is already in use, the CXP 

generates a diagnostic message. 

None. 

Type a filelun symbol. 
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crfile 



Switches 



:f ileid= Function Specifies the file ID to be used when creating 

a file. 
Default 0. 
Syntax Type :fileid= followed by a number between 

and 65535. 

:filetype= Function Specifies the type of the file to be created. 

Default (See the list r below.) 

Syntax Type :filetype= followed by a recognized WMCS 

file type, a file type alias, or a numeral. 

The following file types are supported 
directly by the WMCS : 

Name Value Description 



data 





normal data file 


directory 


1 


directory file 


image 


2 


image file 


ksamdata 


3 


KSAM data file 


ksamkey 


4 


KSAM key file 


11 image 


5 


11 image file 


archcont 


6 


archive continuation file 


encrypt 


7 


encrypted file 


system 


8 


system file 


archive 


9 


archive file 


cipcmd 


10 


CXP and file 


cobol 


11 


COBCL file 


basic 


12 


BASIC file 


pascal 


13 


Pascal file 


object 


14 


object file 



File types 15-255 are reserved by WICAT 
Systems for development and enhancement of the 
WMCS. File types 256-65535 can be defined by 
users. 



crfile -2 



erf ile 



:mode= 



Function Specifies the mode to be used when a file (or 
pipe) is created, opened, or closed. 

Default Depends on what you are doing to the file or 
pipe: 



Action 



Default 



Syntax 



File: create 


write 


File: open 


read 


File: close 


none desired 


Pipe: open 


read 



Note that if you type this switch, you must 
also specify the kind of access you want (see 
the list, under syntax, of what you can 
specify) . In other words, if you type aDode= 
and you want read access, you must type read 
as one of the values for this switch even 
though it may be the default. 
Type anodes followed by any combination of the 
modes listed under the action you want to 
perform. If you specify more than one mode, 
separate the modes by commas. Unique 
abbreviations of the mode names are allowed. 



For example, if you are creating a file, you 
can choose any (as well as any combination) of 
the modes listed under "Create a file", but if 
you are opening a pipe, only four modes are 
available. 

Create a file: 



append nor emote read 

delete notruncfile readLock 

nextfile openif there write 

noreadahead openshared writelock 



Open a file: 

append 
delete^ 
nextf il e 



zerodelete 



noreadahead openshared write 
nor emote read writelock 

notruncfile readlock zerodelete 
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erf ile 



Close a file: 

delete nodelete supalldelete 

forceowrite notruncfile zerodelete 



Open a pipe: 

read readLock 



writelock 



write 



:protection= 



:uic= 



Function Specifies the protection mask for the file to 

be created. 
Default The protection mask specified by the option 

command. 
Syntax Type : protection followed by a protection 

mask. Only the fields you specify in the 

protection mask are altered: unspecified 

fields remain unchanged. 

Function Specify the UIC to be assigned to the new 

file. 
Default Current uic of CEP. 
Syntax Type :uic= followed by a UIC or user name. 



Examples 



erf ile report.dat fnam 

This command creates the file REPORT.DAT in the default directory and 
associates the filelun symbol FNAM with it. The CTP will have write 
access to the file. 

erf ile nyfile2.dat fnam :mo6e=read f write 

This command creates the file MYFILE.DAT in the default directory and 
associates the filelun symbol FNAM with it. The CCP will have read and 
write access to the file. 



Using Prompts 



None. 



erf ile -4 



crfile 



Notes on Usage 



Crfile is typically used for creating and accessing a data file from 
within a command file. 

The status of this operation is assigned to the logical name SYSSRESULT. 

Filelun symbols are distinct frcm symbols, lab-el symbols, and procedure 
symbols, and can therefore have the same names as other types of symbols 
without conflict. 

Filelun symbols cannot be used in expressions. 



Related CIP Commands and Statements 



close Close a file specified by a filelun 

open Open a file and associate a filelun with it 

open pipe Open a pipe associated with output frcm a previous command 

read Read frcm a file 

write Write to a file 

writeln Write a line to a file 
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echo 



Functional Description 



This command parses a command line and displays the result. It is useful 
for seeing exactly what a particular expression might look like after it 
has been processed by the CXP. 



Command Line Syntax 



Mnemonic 

Optional 
parameters 



echo 

CEP string 



Parameters 



CEP String Function Optional. The string that is to be parsed by 

the CEP and then displayed. 
Default Null string. 
Syntax A CEP command. 



Examples 



echo the sky is hLue 

This command will write to SYSSOUTHJT the string "the sky is blue". 



echo -1 



echo 

echo %time() 

This command writes the time to SYS$DUTHJT. 



Using Prompts 



None. 



Notes on Usage 



This is a CXP intrinsic which evaluates its parameters as a CXP 
expression. See the description of CIP (in this dictionary) for 
information on expressions. 



Related CIP Commands and Statements 



write Write a string 

writeln Write a string, followed by a new-line 



echo -2 



for 



Functional Description 



Use this command as a general-purpose looping construct within a CEP 
command file or from an interactive CXP. The for construct allows for an 
optional initial assignment statement, a conditional test expression, and 
another assignment statement (this is very similar to the for command in 
C). 



Command Line Syntax 



Mnemonic 



for 

endfor 



Optional 
parameters 



Initial assignment statement 
Loop condition expression 
FOst loop assignment statement 



Parameters 



Initial 

assignment 

statement 



Function Optional. This assignment statement is used 
to initialize the control variable and is 
performed only once, when the for loop is 
first encountered. A comma follows this 
parameter and separates it from the optional 
test expression. A null initial expression is 
permissible, in which case only a comma will 
precede the second expression. 



for -1 



for 



Default No assignment operation is performed. 

Syntax Type a CXP assignment statement. See the let 

statement for information on the syntax for 

assignment statements. 



Loop 

condition 

expression 



Function Optional. This expression is used to test the 
control variable. The expression is tested at 
the beginning of each iteration of the for 
loop (including the first). Based on the 
result of this expression, two things may 
happen: 

If the result is true (the expression is not 
equal to zero) , all lines immediately after 
the for statement will be executed until an 
endfor is encountered. Processing then 
jumps back to the for statement for re- 
execution. 

If the result of the expression is false 
(the expression is equal to zero), all lines 
immediately after the for statement will not 
be executed until an endfor is encountered. 
Normal processing then resumes. 

Default A null parameter is evaluated as false. 
Syntax Type a CXP expression. 



lost loop 

assignment 

statement 



Function Optional. This statement is separated from 
the optional test expression by a comma. The 
assignment statement can be used to increment 
the control variable and is executed every 
time endfor is encountered, except after the 
for condition expression has failed and the 
for loop has been terminated. 

Default No assignment operation is performed. 

Syntax Type a QP assignment statement. See the CXP 

let statement for information on syntax for 
assignment statements. 



for -2 



for 



Examples 



for a=l r a It SrS^a+l 

writeln "aFSevaKa)" 
endfor 

This example assigns the value 1 to variable A and then enters the for 
loop. At the beginning of each iteration of the loop, including the 
first iteration, the conditional expression is evaluated. If the 
expression proves to be true, the main body of the loop is entered. The 
body of this loop contains one statement that writes the contents of the 
loop variable. Evaluation of loop statements continues until an endfor 
statement is encountered. At that time the third parameter of the for 
construct is executed. Cbntrol then returns to the top of the loop where 
the conditional statement is again evaluated. 



let a=l 

for ,a It 5, 

for l>=a r b It 5,b=bfl 

writeln "a=%eval(a) b=%eval(b)" 

endfor 

let a = a+1 
endfor 

This example shows two for loops, one nested inside the other. For loops 
can be nested to any level. The innermost for and endfor statements 
constitute one loop, and the outermost for and endfor statements 
constitute another loop. The outermost for statement shows that optional 
expressions can be left null. 



Notes on Usage 



For loops can contain any CXP command as part of the body of the for . It 
is permissible to goto a label outside the body of a for , but it is not 
permissible to goto a label nested inside a for . For loops can be nested 
to any level. The range of each loop is marked by an endfor statement. 

The control symbols that are assigned in the for statements are normal 
symbols that can be used elsewhere. At the termination of the for , the 
control symbol has the value it had at the last compare time. 
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for 



Related CEP Commands and Statements 



if Conditional execution of commands 

loop General purpose looping construct 

while Loop while a condition is true 
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goto 



Functional Description 



This command will transfer the flow of a CEP command file to the 
specified label symbol. 



Command Line Syntax 



Mnemonic 

Required 
parameters 



goto 
Label 



Parameters 



Label 



Function Required. Specifies the label of the location 
in the command file to which the CEP will 
transfer command execution. 

Default None. 

Syntax AQP label symbol. 



Examples 



goto nextfoo 

This command tells the CEP to transfer control to the label symbol 
"nextfoo". 



goto -1 



goto 

Using Prompts 
None, 

Notes on Usage 



A goto statement cannot reference the label of an inner or separate block 
(that is, a procedure , if , loop , or other nested constructs) . 

The label can be defined anywhere in the same command file that contains 
the goto statement. If the label has been defined in the command file 
before the goto statement, the CIP transfers control directly to the 
label. If the label is defined after the goto , the CIP searches for the 
label and then transfers control. (If no definition is found, the GP 
exits the command file and generates a diagnostic message.) 

Label symbols are distinct from symbols, procedure symbols, and filelun 
symbols, and can therefore have the same names as symbols of other types. 
Label symbols cannot be used in expressions. 



Related CIP Commands and Statements 



label Declares a CIP label and marks the destination of a goto 

on Go to a label if certain error conditions occur 
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Functional Description 



Use this command as a general-purpose flow-control construct to 
selectively execute instructions based on various conditions. 



Command Line Syntax 



Mnemonic 



if 

else 
elseif 
endif 



Optional 
parameters 



If-expression 

El seif -expr ession 



Parameters 



If-expression 

El seif -expr ession 



Function Optional. This expression is evaluated each 
time the if/ elseif statement is encountered. 
Based on the result of this expression, one of 
several things happens: 

If the result is true (the expression is not 
equal to zero) , all lines immediately after 
the If are executed until an else , elseif or 
endif is encountered. If an else or elseif 
is encountered, all subsequent lines are 
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if 



Default 
Syntax 



skipped until the endif is encountered. 

If the result of the expression is false 
(the expression is equal to zero) , all lines 
immediately after the j£ are not executed 
until an else, elseif . or endif is 
encountered. If an elseif is encountered, 
it evaluates that expression following the 
same rules as an 1£. 

Once an j,£ or elseif expression is 
determined to be true and the ccmmands 
associated with them have been executed, all 
following elseif statements are not executed 
even if their expressions are true. 

The statements following an else are 
executed if the corresponding 1£ or elseif 
expression was found to be false . 

When the endif is encountered, normal 
processing resumes. 

A null parameter is evaluated as false. 
Type a CEP expression. 



Examples 



if a*3+9 gt 5 

time 
elseif b eqs "'pi 1 " 

dir 
elseif c nes " 

dstat 
else 

pstat 
endif 

This statement evaluates each of the i£ and elseif expressions. The 
first expression that is true causes the command under it to be executed. 
Then all other commands are skipped until the endif is encountered. If 
none of the 1£ or elseif commands is true, the command under the else is 
executed. Note that the indentation is unnecessary, but makes the code 
more readable. 
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if 



Notes on Usage 



If statements can contain any CXP command as part of the body of the _i£. 
It is permissible to goto a label outside the boc^ of an _i£, but not to 
goto a label nested inside the body of an _i£. If statements can be 
nested to any level. 



Related CEP Commands and Statements 



loop General purpose looping construct 

while Loop while a condition is true 

for Loop for a specified set of conditions 
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label 



Functional Description 



This command defines a label symbol at the current location. Labels are 
referenced by oq and goto statements. 



Gommand Line Syntax 



Mnemonic 

Required 
parameters 



label 

Label symbol 



Parameters 



Label symbol 



Function Required. Defines a label symbol that can be 

referenced fcy either goto or on statements. 
Default None. 
Syntax A CEP label symbol. 



Examples 



label nextf oo 

This defines the label symbol nextfoo to be at the current location. 
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label 



Using Prompts 



None. 



Notes on Usage 



If a label is inside a procedure, if , loop, or other nested construct, it 
cannot be the target of a goto or oji statement that is outside the nested 
construct. 

The label can be defined anywhere within the command file containing the 
goto statement. If the label definition precedes the goto statement, the 
CIP transfers control directly to the label. If the label definition 
follows the goto , the CIP searches for the definition and then transfers 
control. (If no definition is found, the CIP exits the command file and 
generates a diagnostic message.) 

Label symbols are distinct from symbols, procedure symbols, and filelun 
symbols, and can therefore have the same names as symbols of other types. 

Label symbols cannot be used in expressions. 



Related CIP Commands and Statements 



goto Begins program execution at a specified label 

on Go to a label if certain error conditions occur 
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let 



Functional Description 



This statement assigns an expression to a symbol. 



Command Line Syntax 



Mnemonic 


let 


Required 
parameter 


Symbol 


Optional 
parameter 


Expression 



Parameters 



Symbol 



Function Required. This is the symbol to which the 
expression will be assigned. If this symbol 
has not been defined already, it will be 
defined after the assignment is made. If this 
symbol has a value already, the new value is 
assigned to the symbol. 

Default None. 

Syntax See the CIP command description for 

information on symbol syntax. This symbol 
must be followed by an equal sign. 
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let 



Expression 



Function 



Default 
Syntax 



Optional. After this expression is evaluated 

(and if it is permissible) f the value is 

assigned to the specified symbol. 

A null string. 

Type a CEP expression. See the QP command 

for information on expression syntax. 



Switches 



None. 



Examples 



let a = 3*tempf9 

This command assigns, to the symbol A, the value of the expression. 
let a = "This is a test string" 

This command assigns "This is a test string" to the symbol A. 

let a = 

This command assigns a null string to the symbol A. 



Using Prompts 



None. 



Notes on Usage 



Any permissible expression can be assigned to a symbol. Note that the 
let and the equal sign are required. 

Symbols are local to the current CEP only. They cannot be communicated 
from a child QP to a parent CTP or vice versa. Once a symbol has been 
defined, there is no way to rid the current CTP of it. 
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let 



Symbols are distinct from label symbols, procedure symbols, and f ilelun 
symbols and can therefore have the same names as symbols of other types. 



Related CIP Commands and Statements 



None. 
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lineclr 



Functional Description 



This command erases from the current, or a specified, position to the end 
of a line on the screen. 



Command Line ^ntax 



Mnemonic 



lineclr 



Optional 
parameters 



Row number 
Column number 



Parameters 



Row number Function Optional. Specifies row number to clear from. 

Default Current row number. 
Syntax Any valid expression. 



Golumn number 



Function Optional. Specifies the number of the column 

at which the clearance begins. 
Default Current column number. 
Syntax Any valid expression. 
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lined r 



ExampLes 



lined r 

This command erases from the cursor to the end of the line and leaves the 
cursor unaffected. 

linedr 17 4 

This erases from row 17, column 4 to the end of the line and leaves the 
cursor at row 17, column 4. 



Using Prompts 



None. 



Notes on Usage 



The upper left-hand corner of the screen is position 1,1. 

This is a QP intrinsic that evaluates its parameters as a CXP 
expression. 

You can omit the rcw and column parameters only if your terminal has a 
hardware erase-to-end-of-line command. If not, the QP generates a 
diagnostic message when you try to execute the statement. 

Specify both parameters, or none. 

If termopen has not been called before the first invocation of lineclr , 
scrnclr , or scrnpos, termopen will be called automatically. 

You can specify any set of coordinates: no check is performed to see 
whether the position is on the screen. Terminals may react differently 
and unpredictably if an invalid screen address is given. 
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lineclr 



Related CIP Commands and Statements 



scrnclr Qear to end of screen 

scrnpos Position screen cursor 

termopen Initialize screen routines 
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log 



Functional Description 



Use this command to terminate the QP in which you are working. 



Command Line Syntax 



Mnemonic 
Switches 



log 

rhangup 
:save 



:log 



:perm 



:result= 



Parameters 



None. 



Switches 



:hangup 



Function Tells the QP whether or not to send a hangup 

command to SYS$INKJT. 
Default : hangup 
Syntax Type :nohangup to keep the CEP from sending a 

hangup to SYS$INHJT. 
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log 

:log 



:perm 



:result= 



:save 



Function Specifies whether or not log messages are 
displayed by utilities. (Log messages report 
on what the utility is doing.) 

Default The value specified for the option command. 
(The default for option is :log. ) 

^■ntax iype :nolog or :log. 

Function Specifies whether or not you want the change 
(specified by the command) to last even after 
execution of the current CXP is complete. For 
exanple, :perm in a command file makes the 
change specified on that line persist after 
execution of the command file is complete. Used 
with log , this switch logs you out of all 
nested command files and puts you in your last 
(or most recent) interactive CEP. 

Default :noperm 

Syntax Type :penn or tnoperm. 

Function Tells the CXP whether or not to return an 

explicit abort reason to the parent process. 
Default CXP returns an abort reason of zero. 
Syntax Type :result= followed by a CLP expression. 

Function Specifies whether or not the QP saves the 
current command-stack buffer in file CEPOID.STK 
in your home directory. 

Default :save. 

Syntax Type rnosave to keep the CEP from saving the 

copy of the command- stack buffer. 



Examples 



log 

This command terminates the CEP the user is executing and displays the 
following kind of message: 

AL logged off at 15-Apr-1985 08:40:37 

Note that the user name, date, and time are displayed when the user logs 
off. 
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log 



log :nolog 



This aornmand terminates the CXP the user is executing, but suppresses the 
display of the log message. 



log :penn 

If this command is executed from inside a command file, it terminates all 
levels of the command file back to the previous interactive CXP. If LOG 
is executed from an interactive CXP, it terminates that CXP only. Then 
this kind of message appears: 



AL logged off at 15-Apr-1985 08:40:37 



log :result=1000 



The parent process receives an abort reason of 1000. This is a way for a 
command file to signify status to a parent process or command file. 



Using Prompts 



None. 



Notes on Usage 



As the oldest parent CIP is terminating, it executes a command file 
called LOGOFF. (EM located in SYSSDISK/SYSLIB. This command file in turn 
executes SYS$DISK/SYaLIB/LOCALOFF.O0M and USERDFF.ODM located in the 
user's home directory. 



NOTE: If log is executed from within a command file or from a nested CIP, 
LOGOFF. QOM, LOCALOFF. OOM, and USEPOFF. 00M are not executed. 



Related CEP Commands and Statements 



cip Execute a copy of CI P. EXE 
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loop 



Functional Description 



Use . this command as a general-purpose loo ping-construct within a QF 
command file or from an interactive CLP. This statement instructs 
processing to loop while one or more given expressions are true. 



Command Line Syntax 



Mnemonic 



loop 

exitif 

endLoop 



Optional 
parameter 



Exit conditional expression (exitif only) 



Parameters 



Exit 

conditional 

expression 



Function Optional. This parameter specifies the 
condition under which the loop is to be 
exited. If the result of the expression is 
true (non-zero) , then the loop is exited and 
control passes to the statement immediately 
following endloop . If the result of the 
expression is false (zero) , control passes to 
the statement after exitif . 
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loop 



Default If no expression is specified, a value of 

false will be used. 
Syntax Type a CTP expression. 



Examples 



let a = 1 
loop 

writeln "»=%eval(a)" 

let a = a + 1 

exitif a > 10 
endLoop 
writeln "All done" 

This example assigns the value 1 to the symbol A and then enters the 
loop. The body of this loop contains three statements. The first 
statement writes the contents of A. The next statement increments the 
symbol A. The next statement in this loop shows the use of exitif that 
causes the loop to be exited when the value of the symbol A exceeds 10. 
Evaluation of loop statements continues until an endloop statement is 
encountered. Control then returns to the top of the loop. 



Notes on Usage 



Loop statements can contain any CEP command as part of the body of the 
loop. You can goto a label outside the body of a loop, but not to a label 
nested inside a loop. Loop statements can be nested to any level. The 
range of each loop is marked with endloop . 

If a loop is not exited by log or goto , then the only way to exit the 
loop is by satisfying the conditional expression of an exitif statement 
within the body of the loop. Any number of exitif statements (or none at 
all) can be specified in a loop . 



Related CEP Commands and Statements 



if Conditional execution of commands 

for Loop for a specified set of conditions 

while Loop while a condition is true 
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on 



Functional Description 



This command defines what the CEP should do when it is executing a 
command file and a [CTRL] c is pressed, or an error or warning is 
returned from a command (or process) that it is executing. 



Command Line Syntax 



iMnemonic 



on 



Required 
parameters 



Error type 
Error state 



Parameters 



Error type Function Required. This parameter specifies which of 

the three types of errors you want to handle. 
Default None. 

Syntax Type one or more of the following names 

separated by commas (unique abbreviations are 
allowed) : controlc, error, warning. 



Error state Function Required. This parameter specifies what will 

be done when the given state (s) occur (s) . 

Default None. 

Syntax You can type continue, abort, or a label symbol 

defined in the command file. Continue means to 
ignore the error type(s) and go on. Abort 
means to terminate execution of the command 
file. A label symbol means to locate the given 
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on 



label and transfer the flew of execution to 
that label. Note that there is no way to know 
exactly where you came from when a label is 
entered this way. Note that continue and abort 
are reserved words and cannot be used as label 
symbols with this command. 



Switches 



None. 



Examples 



on controlc continue 

After this command is executed in a command file, if the user should 
press [CTRL] c, the CXP will ignore it and continue the normal execution 
of the command file. 

on error,warning handle 

After this command is executed in a command file, if an error or warning 
is returned from any command, the CEP will transfer process flow to the 
label symbol "handle". 



Using Prompts 



None. 
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on 



Notes on Usage 



When the QP initiates execution of a command file, the default state of 
the three error types is: 

Error type Error state 

control c abort 

error continue 

warning continue 

You can have as many oq statements as you want in a command file. In the 
case of conflicting on. statements, the most recently executed statement 
is in effect. 

This command has no meaning if executed from an interactive CI P. 



Related CIP Commands and Statements 



goto Go to a label 

label Define a label 
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open 



Functional Description 



This command opens an existing file and associates it with the specified 
filelun symbol. 



Command Line Syntax 



Mnemonic 

Required 
parameters 

Switches 



open 

Filename 
Filelun 

:mode= 



Parameters 



Filename 



Function Required. The name of the file to be opened. 

Default None. 

Syntax Type a file designation. 



Filelun 



Function 



Default 
Syntax 



Required. The name of the filelun symbol 

be associated with the file to be opened. 

the filelun symbol is already in use, 

diagnostic message results. 

None. 

Type a filelun symbol. 



to 

If 

a 
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open 



Switches 



:mode= 



Function Specifies the mode to be used when a file (or 
pipe) is created, opened, or closed. 

Default Depends on what you are doing to the file or 
pipe: 



Action 



Default 



Syntax 



File: create 


write 


File: open 


read 


File: close 


none desired 


Pipe: open 


read 



Note that if you type this switch, you must 
also specify the kind of access you want (see 
the list, under syntax, of what you can 
specify) . In other words, if you type anode= 
and you want read access, you must type read 
as one of the values for this switch even 
though it may be the default. 
Type :mode= followed by any combination of the 
modes listed under the action you want to 
perform. If you specify more than one mode, 
separate the modes by commas. Unique 
abbreviations of the mode names are allowed. 



For example, if you are creating a file, you 
can choose any (as well as any combination) of 
the modes listed under "Create a file", but if 
you are opening a pipe, only four modes are 
available. 

Create a file: 



append nor emote read 

delete notruncfile readLock 

nextfile openif there write 

noreadahead openshared writelock 



Open a file: 

append 
delete 
nextf il e 



zerodelete 



noreadahead openshared write 
nor emote read writelock 

notruncfile readLock zerodelete 
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open 



Close a file: 

delete nodelete supalldelete 

forced* rite notruncfile zero delete 

Open a pipe: 

read readLock writelock write 



Examples 



open "nyfile.dat" fnam 

This command opens the file MYFILE.EAT and associates the filelun symbol 
fnam with it. The CEP will have read access to the file. 

open "nyfile2.dat" fnam anode=write r writelock, append 

This command opens the file MYFILE.DAT and associates the filelun symbol 
fnam with it. The file is opened for write access. It will be opened 
write-locked to prevent any other users from opening the file while this 
process has the file open, and the file position will be set to the end 
of the file to facilitate appending data to the existing file. 



Using Prompts 



None. 



Notes on Usage 



Open is generally in a command file to access a data file. 

A report of the status of this operation is sent to the logical name 
SYSSRESULT. 

Filelun symbols are distinct from symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 
Filelun symbols cannot be used in expressions. 
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open 



Related CXP Commands and Statements 



erf He Create a file and associate a f ilelun with it 

close dose a file specified by a f ilelun 

open pipe Open a pipe associated with output from a previous command 

read Read from a file 

write Write to a file 

writeln Write a line to a file 
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openpipe 



Functional Description 



Use this command to read the output of a program whose output or error 
was directed to a pipe. Openpipe opens that pipe for reading with the 
associated f ilelun symbol. 



Command Line Syntax 



Mnemonic openpipe 

Required Filelun 
parameters 

Switches :mode= 



Parameters 



Filelun Function Required. The name of the filelun symbol to 

be associated with the file opened via 
openpipe . If the filelun symbol is already in 
use f a diagnostic message results. 



Default None. 

Syntax Type a filelun symbol. 
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openpipe 



Switches 



:mode= 



Function Specifies the mode to be used when a file (or 
pipe) is created, opened, or closed. 

Default Depends on what you are doing to the file or 
pipe: 



Action 



Default 



File: create 


write 


File: open 


read 


File: close 


none desired 


Pipe: open 


read 



Note that if you type this switch, you must 
also specify the kind of access you want (see 
the list, under syntax, of what you can 
specify) . In other words, if you type anode= 
and you want read access, you must type read 
as one of the values for this switch even 
though it may be the default. 
Syntax lype anDde= followed by any combination of the 

modes listed under the action you want to 
perform. If you specify more than one mode, 
separate the modes by commas. Unique 
abbreviations of the mode names are allowed. 

For example, if you are creating a file, you 
can choose any (as well as any combination) of 
the modes listed under "Create a file", but if 
you are opening a pipe, only four modes are 
available. 

Create a file: 



append nor emote read 

delete notruncfile readLock 

nextfile openif there write 

noreadahead openshared writelock 



zerodelete 



Open a file: 

append 
delete 
nextfile 



noreadahead openshared write 
nor emote read writelock 

notruncfile readlock zerodelete 
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openpipe 

Close a file: 

del ete nodel ete supal 1 del ete 

forcectorite notruncfile zerodelete 

Open a pipe: 

read readlock writelock write 



Examples 



dir * :nohead :path :sup£cess=version popenpipe fLun 

This command forks dir and redirects output and error to a pipe. It then 
opens that pipe for reading with the associated f ilelun symbol. The (HP 
will have read access to the pipe. 



Using Prompts 



None. 



Notes on Usage 



Openpipe is generally used from within a command file to facilitate CTF 
access of data generated by another process. 

You should redirect both SYS$ERROR and SYS$CUTRJT to the pipe if the 
command will be sutmitted to a batch queue. 

Filelun symbols are distinct from symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 
Filelun symbols cannot be used in expressions. 
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openpipe 



Related QP Commands and Statements 



erf ile Create a file and associate a f ilelun with it 

close Close a file specified by a filelun 

open Open a file for access by specified filelun 

read Read from a file 

write Write to a file 

writeln Write a line to a file 
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option 



Functional Description 



Use this command to dispLay or specify a (HP control option, 



Command Line ^ntax 



Mnemonic 


option 


Switches 




Options for 
utilities 


terror 
t pause 


Options for 


tperm 
tverify 



slog 



:prompt= 



tmessage 



:path= 



tprotection= ttrace 



Parameters 



None. 
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option 



Switches 



: error 


Function 




Default 




Syntax 


:log 


Function 




Default 




Syntax 


rmessage 


Function 




Default 




Syntax 


:path= 


Function 




Default 




Syntax 



Tells the CXP whether or not to have utilities 

display the standard 3-line diagnostic message 

when an error occurs. 

terror 

Type rnoerror to prevent CXP utilities from 

displaying diagnostic messages. 

Specifies whether or not log messages are 

displayed by utilities. (Log messages report 

on what the utility is doing.) 

The value specified for the option command. 

(The default for option is :log.) 

Type :nolog or :log. 

Tells the CLP whether or not utilities are to 

display the third (or explanation) line of the 

standard 3-line diagnostic message that is sent 

to SYS$CUTRJT when an error occurs. 

rmessage 

Type rncmessage to suppress the explanation 

line of diagnostic messages. 

Specifies the path the CEP follows to search 
for image files and ccmmand files for which no 
path is specified when the filename is typed on 
the command line. 

: pa th= , /sy se xe/ ,/sy se xe . sgs/ ,/sy se xe . user s/ 
Type :pati^ followed by a pathname or list of 
pathnames (items in a list are separated fcy 
commas) . A null path means the default 
directory. If there is a leading slash (such 
as those shown, above, for the default) in a 
directory string, SYS$DISK is appended to the 
front of the directory string. If a leading 
slash is not part of a directory string, the 
CEP looks at the default disk. You can include 
devicenames in these strings. 
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option 



: pause 



Function Specifies whether utilities will automatically 
pause after presenting a screenful of data. 

Default : no pa use 

Syntax Type :pause to engage pausing, mopause to 

disengage it. 



NOTE: You can override the setting of this 
switch, when you execute a utility, by 
typing : pa use or mopause on the command 
line. 



:perm 



Function 



;prcmpt= 



Default 
Syntax 

Function 

Default 

Syntax 



:protection= Function 

Default 
Syntax 



Specifies whether or not you want the change 
(specified by the ccmmand) to last even after 
execution of the current CEP is complete. For 
example, :perm in a ccmmand file makes the 
change specified on that line persist after 
execution of the ccmmand file is complete. Used 
with log , this switch logs you out of all 
nested ccmmand files and puts you in your last 
(or most recent) interactive a P. 
moperm 
Type :perm or :noperm. 

Tells the CEP what kind of prompt to print 

while the CEP waits for the next command. 

A right angle-bracket is the default prompt for 

a CIP created at logon. All child CIPs have 

this prompt: CEP> 

Type :pr aupL= followed by the prompt. If the 

prompt string contains an intrinsic function 

preceded by an accept character (for example, 

\%time()), the CEP re-evaluates the prompt 

string each time the prompt string is written. 

Specifies the default protection mask for the 

CIP. When a utility creates a file, this 

protection mask is assigned to it. 

The protection mask specified in SYSLIB/ 

UAF.DAT. 

Type :protectioff= followed by a protection 

mask. Only the fields you specify are 

modified: unspecified fields remain unchanged. 
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option 



rtrace 



Function 



Default 
Syntax 



Specifies whether or not you want to see what 

lines are being executed after the CEP has 

parsed the lines in the command file. 

motrace 

Type rtrace to show the lines as they are 

executed. 



rverify 



Function 



Default 
Syntax 



Tells the CXP whether or not to display the 

lines in the command file, before they are 

executed, exactly as they appear in the file. 

moverify 

Type rverify to have lines displayed before 

they are executed. 



Examples 



option 

This command produces a display of the status of all CLP control options. 
For example: 



SYSSRESULT : 





Home : 


SYS SDISK/USERS. TEST/ 


Bath : 


r /sy sexe/ ,/sy sexe. sgs/ ,/sy sexe. users/ 


Prompt : 


TEST> 


Protection • 


S: RE,P: ,G: WRE,0:DWRE 


User name 


TEST 


Error : 


Yes 


Log 


Yes 


Message 


. Yes 


Pause 


: No 


Trace 


. No 


Verify 


: No 



option rverify mcmessage 

The rverify switch causes all command files to display the contents of 
the command file before the file is executed. The mcmessage switch 
suppresses the message line of an error display when an error occurs. 
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option 



option :pcanpt=*Pest> " :peim 



This command changes the CEP prompt to Test>. If this command is 
executed inside a command file, it changes the prompt of the interactive 
CXP from which the command file was executed — the new prompt is Test>. 
By placing this kind of command in your USERJP.CDM file you can define 
the kind of prompt assigned to you when you log on. 

option :pcon53t="A%olrectory(^%default()" f l)/ \%copy("\%tiine()" f lr5)> " 

This command changes the user's prompt to show the default directory and 
the hours and minutes of the current time. Each time a new command is 
executed, the user's directory and the time are re-evaluated and the 
prompt is updated. Were the user in SYS $DISK/SYSEXE. USERS/ and were the 
time 10:14 am, the prompt would look like this: 

/.USERS/ 10:14> 



Using Prompts 



None. 



Notes on Usage 



Use the :perm switch in command files to assign option characteristics 
for an interactive CI P. Note that option applies to only the most recent 
interactive CTP. 



Related CEP Commands and Statements 



None. 
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pause 



Functional Description 



This command delays processing for a specified number of ticks 
(100 ticks = 1 second). 



Command Line Syntax 



Mnemonic 

Optional 
parameters 



pause 
Delay 



Parameters 



Delay 



Function Optional. Specifies number of ticks to delay 

(100 ticks = 1 second) . 
Default ticks. 
Syntax AQP expression. 



Examples 



pause 150 

This command delays processing for 1.5 seconds. 



pause -1 



pause 



Using Prompts 



None. 



Notes on Usage 



This is a CEP intrinsic that evaluates its parameters as a CTP 
expression. 



Related CXP Commands and Statements 



wait Wait until specified time, then send a message 
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Pd 



Functional Description 



Every time a user executes c£, the directory just entered is saved on a 

stack. J23 moves the user to the top directory on the stack and then 

removes that entry from the stack. This stack holds only the last eight 
directories. 



Command Line Syntax 



Mnemonic pd 

Switches :log :perm 



Parameters 



None. 



Switches 



:log Function Specifies whether or not log messages are 

displayed by utilities. (Log messages report 
on what the utility is doing.) 

Default The value specified for the option command. 
(The default for option is :log.) 

Syntax Type rnolog or :log. 
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Pd 



:perm 



Function Specifies whether or not you want the change 
(specified by the command) to last even after 
execution of the current CEP is complete. For 
exanple, :perm in a command file makes the 
change specified on that line persist after 
execution of the command file is complete. Used 
with loo, this switch logs you out of all 
nested command files and puts you in your last 
(or most recent) interactive CI P. 

Default :noperm 

Syntax Type :penn or :noperm. 



Examples 



cd .test 

_DC0/USERS.TEST/ 

pd 

_DC0/USERS/ 

In the foregoing example, the user changes the default directory from / 
USERS/to /USERS. TEST/, id then changes the default back to /USERS/. 



Using Prompts 



None. 



Notes on Usage 



If .pd is executed and there are no more entries on the stack, jod does not 
change the default directory, but reports the name of the default 
directory already assigned. 
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Pd 



Related CIP Commands and Statements 



def Display the name of the default device directory 

crd Create a directory 

cd Change to a given device and directory 



pd -3 



procedure 



Functional Description 



Use this command to define a procedure that can be called by a QP 
command file. A procedure can be executed only by using a call statement 
(that is, procedures are not executed as QP encounters them in a command 
file, but only in response to a call that specifies that procedure) . 
When a procedure is called, it will execute until it encounters either a 
return statement or an endprocedure statement. Any number of return 
statements can appear in a procedure definition. 



Command Line ^ntax 



Mnemoni c pro cedur e 

endprocedure 

Required Procedure name 

parameter 



Parameters 



Procedure name Function Required. Use this parameter to specify the 

name of the procedure you want to define. 
Default None. 
Syntax Type a procedure symbol. 
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procedure 



Examples 

procedure get_sysexe_dir 
if 'pi 1 eqs ■" 

return 
endif 

dir sysSaisk/sysese/'pl' >exedir.dat tnohead :path :suppcess=version 
if 'pi' eqs ■*■ 

return 
else 

nyprogram 'pi 1 
endif 
endprocedure 

This example defines a procedure named GET_SYSEXE_DIR. This procedure 
does the following. It returns immediately if the value of parameter Pi 
is a null string. If the Pi parameter is not null, a specialized 
directory listing of a particular file or set of files in SYS$DISK/ 
SYSEXE/ is made to an output file called EXEDIR.EAT. The procedure then 
returns immediately or executes another program based on the value of 
parameter Pi. 



Notes on Usage 



The programmer determines the functionality of a procedure. Procedures 
can manipulate global parameters, symbols, and logical names; call other 
procedures; invoke programs; use other commands and statements intrinsic 
to the CEP, etc. 

A procedure can be of any length, limited only by available memory. 

Control returns from a procedure to its caller when the QP encounters a 
return or endprocedure . 

The specified procedure can be defined anywhere in the command file that 
contains the call statement. If the definition of the procedure precedes 
the call statement, the GP transfers control directly to the procedure. 
If the definition follows the call statement, the CLP searches for the 
definition and then transfers control. (If no definition is found, the 
QP exits the command file and generates a diagnostic message.) 
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procedure 



The return statement can appear anywhere in the procedure, even inside 
control structures such as loop , if , etc. If a return statement is found 
outside of a called procedure, the CUP exits the command file and 
generates a diagnostic message. A procedure can contain any number of 
return statements. 

Endprocedure acts as an implicit return statement at the end of a 
procedure. 

A procedure must have an endprocedure as its last statement regardless of 
whether there are any return statements in the procedure. 



Related QP Commands and Statements 



call Call a procedure 
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read 



Functional Description 



This command reads from an open f ilelun symbol into a symbol. 



Command Line Syntax 



Mnemonic 


read 






Optional 
parameter 


Filelun 






Required 
parameter 


Symbol 






Switches 


:editmode= 
:recnum= 


: emmodify= 
:timeout= 


:numr ecs : 



Parameters 



Filelun 



Function Optional. The name of the filelun symbol 
associated with the file to be read. If the 
filelun symbol has not been defined, a 
diagnostic message results. 

Default If only one parameter is given for this 
command, the QP assumes that this is the 
symbol. The predefined filelun symbol SYS IN 
is used. 

Syntax Type a filelun symbol. 



read -1 



read 

Symbol 



Function Required. The name of the symbol to read the 

data into. 
Default None. 
Syntax A symbol. 



Switches 



:editmode= 



:emmodify= 



Function 

Default 
Syntax 



Function 

Default 
Syntax 



:numrecs= 


Function 




Default 




Syntax 


:recnum= 


Function 




Default 




Syntax 


:timeout= 


Function 




Default 




Syntax 



Specifies the edit mode to be used when 

reading. 

lineall 

Type :editmode= followed by one of the 

following edit-mode values: 



line linewchr 

linewchrall 



raw lineall 



Specifies the modifiers to the edit mode 

switch. 

None. 

Type :emDOdify= followed by any combination of 

the following modifiers, separated by commas 

(unique abbreviations are allowed) : 



lock 



noecho 



Specifies the number of bytes to be read. 

127 bytes. Inasmuch as a line is usually 

requested, the amount of data actually read 

varies. 

Type :nunrecs= followed by an expression. 

Specifies the position in the file at which 

the operation is to be performed. 

Current record position. 

Type :recnun= followed by an expression. 

Specifies how long the CXP must wait before 

canceling the operation. 

-1. This is essentially unending. 

Type :timeout= followed by an expression. This 

number is in l/lQ0ths of a second. 
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read 



Examples 



read fnam nysymb 

This command reads a line of data from the file associated with the 
f ilelun fnam and saves the data in the symbol mysymb. 

read resp :timeout=1000 

This command reads from SYS$INHJT and saves the data in the symbol resp. 
If nothing is read before the 10-second timeout has expired, a null 
string is inserted in the symbol resp. The status of this operation 
appears in the logical name SYS RESULT. 



Using Prompts 



None. 



Notes on Usage 



Read is generally used for accessing a data file frcm a command file. 

The status of this operation is sent to the logical name SYS$RESULT. A 
standard 3-line message display is given for all errors except 
ERRREAELEOF (140) and ERRTIMECUT (128) . 

Filelun symbols are distinct frcm symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 
Filelun symbols cannot be used in expressions. 
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read 



Related CEP Canmands and Statements 



close dose a file specified by a f ilelun 

erf ile Create a file and associate a filelun with it 

open Open a file and associate a filelun with it 

openpipe Open a pipe associated with output from a previous command 

write Write to a file 

writeln Write a line to a file 



read -4 



return 



Functional Description 



Use this command to return from a procedure. 



Command Line Syntax 



Mnemonic return 



Parameters 



None. 



Switches 



None. 



return -1 



return 



Examples 



procedure test 
for i=l, i le 100 , i=i+l 
if i >= ret 
return 
endlf 
• • • 
endfor 
endprocedure 

This procedure causes an immediate return from the procedure if the loop 
counter reaches the value of the variable ret. 



Notes on Usage 



A return can appear anywhere in a procedure. It can also be placed 
inside other flow-control constructs ( for , if , while , etc.). A procedure 
can contain any number of return statements. Note that a return 
statement is unnecessary at the end of a procedure because endprocedure 
acts as an implicit return . 

Even if a return statement is used, endprocedure is required to define 
the end of the body of the procedure. 



Related CTP Commands and Statements 



call Call a procedure 

procedure Define a procedure 
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scrndr 



Functional Description 



This canmand erases from the current psition (or a given position) to 
the bottom of the screen. 



Command Line Syntax 



Mnemonic 



scrnclr 



Optional 
parameters 



Row number 
Column number 



Paraneters 



Row number Function Optional. Specifies row number from which 

clearance begins. 
Default Current row number. 
Syntax An expression. 



Column number 



Function Optional. Specifies column number at which 

clearance begins. 
Default Current column number. 
Syntax An expression. 
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scrnclr 



Examples 



scrnclr 

This ooinmand erases from the cursor to the end of the screen and leaves 
the cursor unaffected, 

scrndr 17 4 

Erases from row 17, colimn 4 to the end of the screen and leav.es the 
cursor at row 17, column 4. 



Using Prompts 



None. 



Notes on Usage 



The upper left-hand corner of the screen is position 1,1. 

This is a CEP intrinsic that evaluates its parameters as a CEP 
expression. 

You can omit the row and column parameters only if your terminal has a 
hardware erase-to-end-of-screen command. If not, a diagnostic message 
results when you omit the row and column numbers. 

Specify both parameters, or neither. 

If termopen has not been called before the first invocation of lineclr , 
scrnclr , or scrnpos, the (IP automatically calls termopen . 

You can specify any coordinates — the CEP does not check to determine 
whether the specified position is on the screen. Terminals may react 
differently and unpredictably" if an invalid screen address is given. 
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scrnclr 



Related CIP Gcfrnmands and Statements 



lined r Qear to end of- line 

scrnpos Ibsition screen cursor 

termopen Initialize screen routines 
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Functional Description 



scrnpos 



Ihis command positions the cursor, 



Command Line Syntax 



Mnemonic 

Required 
parameters 



scrnpos 

Row number 
Column number 



Parameters 



Row number Function Required. 

coordinate. 
Default None. 
Syntax An expression. 



Specifies the row-number 



Column number 



Function Required. Specifies the column-number 

coordinate. 
Default None. 
Syntax An expression. 
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scrnpos 

Examples 

scrnpos 17 4 

This command positions the cursor at row 17, column 4 

Using Prompts 
None. 

Notes on Usage 



The upper left-hand corner of the screen is position 1,1. 

This is a CXP intrinsic that evaluates its parameters as a QP 
expression. 

If termopen has not been called before the first invocation of lineclr , 
scrnclr , or scrnp os , the CEP automatically calls termopen automatically. 

You can specify any coordinates: the QP does not check to see whether 
the specified position is on the screen. Different terminals react 
differently and unpredictably if an invalid screen address is given. 



Related CIP Commands and Statements 



lineclr Clear to end of line 

scrnclr Clear to end of screen 

termopen Initialize screen routines 
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syntol 



Functional Description 



Use this command to display all symbols that have been defined in the 
current CEP, along with the current value of each. 



Gommand Line Syntax 



Mnemonic symbol 



Parameters 



None. 



Switches 



None. 
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syiifcol 



Examples 



symbol 

poem = "mary had a little lamb" 
num = "354" 
x= "-34" 

In this example, the values of the symbols available to this process are 
displayed. 



Notes on Usage 



The CEP uses a hashing algorithn to store symbols. This algorithm 
provides rapid access to specific symbols, but cbes not lend itself to 
alphabetical or other ordered-storage organization. Therefore, the 
output from symbol is not in any recognizable order; it reflects the 
order of the symbols as they are found in the hash table. To obtain a 
sorted listing of symbols you must redirect the output of symbol to a 
file and then use wsort to sort the file. 



Related QP Commands and Statements 



let Assign an expression to a symbol 

for Loop for a specified set of conditions 
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tennopen 



Functional Description 



This command initializes the terminal output routines of the CLP for a 
particular terminal. 



Command Line Syntax 



Mnemonic 

Optional 
parameter 



termopen 
Setupout 



Parameters 



Setupout 



Function Optional. Specify the setup file to be used 

for terminal output from lineclr , scrnclr, and 

scrnpog. 
Default Uses the setup file associated with 

SYS SCUT PUT. 
Syntax The syntax for each allowable case is 

described below: 

Just a name can be specified (for example, 
vtl00) . If you specify a name, the CEP 
searches for the setup file in SYS$DISK/ 
SYSL IB. SETUP/. Ihe given name will be used 
with the extension . STP if it was not 
specified already. 
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tennopen 



Just a path can be specified (for example, 
SYS $DISK/USER. SETUP/). In this case the 
CEP searches the specified directory for 
the setup file, A name is generated as 
described above. If no extension is 
specified, .STP is used. 

A path and a name can be specified (for 
example, SYS$DISK/USER.SETUP/£BC) . In this 
case the (HP searches for the specified 
file in the directory specified. If no 
extension is specified, .STP is used. 



Examples 



tennopen 

This command initializes the terminal output routines using the 
appropriate setup file for SYSSCUTRJT in SYS $DISK/SYSL IB. SETUP/. 

tennopen wit 

This command initializes the terminal output routines using the setup 
file SYS SDISK/SY^IB. SETUP/WIT. STP. 



Using Prompts 



None. 



Notes on Usage 



If lineclr, scrnclr , or scrnpos are called before tennopen is called, 
they perform an implicit call to termopen to initialize the screen 
parameters. It will function as if you did not specify a parameter to 
termooen. 
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tennopen 



Related CIP Commands and Statements 



lined r Qear to end of line 

scrnclr Qear to end of screen 

scrnpos losition screen cursor 
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while 



Functional Description 



Use this command as a general- pur pose looping construct within a CXP 
command file or from an interactive CEP, This construct loops while a 
given expression is true. 



Command Line Syntax 



Mnanonic 



while 
encWhile 



Optional 
parameter 



Expression 



Parameters 



Expression Function Optional. This expression is evaluated each 

time the while statement is encountered. 
Based on the result of this expression, two 
things happen: 

If the result is true (the expression is 
not equal to zero) , all lines immediately 
after while are executed until endwhile is 
encountered. Control then returns to the 
while statement for re-execution. 
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while 



If the result of the expression is false 
(the expression is equal to zero) , all 
lines immediately after while are not 
executed until endwhile is encountered. 
Normal processing then continues. 

Default A null string is evaluated as false. 
Syntax Type an expression. 



Examples 



let a = 1 
while (a It 10) 

writeln "a^evaKa)" 

let a = a + 1 
endwhile 
writeln "All done" 

This example assigns the value 1 to variable A and then enters the while 
loop. At the beginning of each iteration of the loop, the conditional 
expression is evaluated, and if the expression is true, the main body of 
the loop is entered. The body of this loop contains two statements. One 
statement writes the value of the symbol A. The other statement 
increments the symbol A. Evaluation of loop statements continues until an 
endwhile statement is encountered. Gontrol then returns to the top of 
the while statement, where the conditional statement is reevaluated. If 
the conditional statement is found to be false, control is transferred to 
the statement immediately after the endwhile statement that belongs to 
the while statement. 



Notes on Usage 



While statements can contain any CTP command as part of the body of the 
while statement. You can goto a label outside the body of a while 
statement, but not to a label nested inside the body of a while 
statement. While statements can be nested to any level. 
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while 



Related CIP Commands and Statements 



if Conditional execution of commands 

loop General purpose looping construct 

for Loop for a specified set of conditions 
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write 



Functional Description 



This canmand writes to an open filelun symbol from a local symbol, 
expression, or literal string. 



Canmand Line Syntax 



Mnemonic 


write 






Optional 
parameter 


Filelun 






Required 
parameter 


Expression 






Switches 


:editmode= 
:recnum= 


: emmodify= 
:timeout= 


:numrecs : 



Parameters 



Filelun 



Function Optional. The name of the filelun symbol 
associated with the file to be written. If 
the filelun symbol is not defined, a 
diagnostic-message results. 

Default If only one parameter is given for this 
command, then it is assumed to be the symbol. 
The predefined filelun symbol SYSIN is used. 

Syntax A filelun symbol. 
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write 



Expression Function Required. This is the expression that is to 

be written to the specified f ilelun. 

Default None. 

Syntax Any CIP expression (including a literal 
string) . 



Switches 



:editmode= Function Specifies the edit mode to be used when 

writing. 
Default line. 

Syntax Type :editmode= followed by one of the 

following edit-mode values: 



line 



raw 



:emmodify= Function Specifies the modifiers to the edit mode 

switch. 

Default none. 

Syntax Type :eHmodify= followed by any combination of 

the following modifiers, separated by commas 
(unique abbreviations are allowed) : 

forceowrite unlock 



:numrecs= 



:recnum= 



:timeout= 



Function Specifies the number of bytes to be written. 

Default The size of the expression. 

Syntax Type :nimrecs= followed by an expression. 

Function Specifies the position in the file at which 

the operation is to be performed. 
Default Current record position. 
Syntax Type treaiuiF 5 followed by an expression. 

Function Specifies how long the CEP must wait before 

canceling the operation. 
Default -1. This is essentially unending. 
Syntax Type :timeout= followed by an expression. This 

number is in l/100ths of a second. 
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write 



Examples 

write fnam nysymb 

This command writes the data from the symbol mysymb to the file 
associated with the f ilelun fnam. 

write *Ehis is a string to write" 

This command writes the specified string to SYS$CUTRJT. 



Using Prompts 



None. 



Notes on Usage 



Write is generally used for accessing a data file from a command file. 

The report of the status of this operation is sent to the logical name 
SYS SRESULT. A standard 3-line message display is given for all errors 
except ERRREAELEOF (140) and ERRTIMECUT (128). 

Filelun symbols are distinct frcm symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 
Filelun symbols cannot be used in expressions. 



Related CEP Commands and Statements 



close Close a file specified by a filelun 

erf ile Create a file and associate a filelun with it 

open Open a file and associate a filelun with -it 

openpipe Open a pipe associated with output from a previous command 

read Read from a file 

writeln Write a line to a file 
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writeln 



Functional Description 



This command writes to an open filelun symbol from a local symbol, 
expression, or literal string, and inserts a new line after the data 
written. 



Command Line Syntax 



Mnemonic 

Optional 
parameter 

Required 
parameter 

Switches 



Writeln 
Filelun 

Expression 



:editmode= 
:recnum= 



:emmodify= 
:timeout= 



:numrecs= 



Parameters 



Filelun 



Function Optional. The name of the filelun symbol 
associated with the file to be written. If 
the filelun symbol is not defined, a 
diagnostic message results. 

Default If only one parameter is given for this 
command, it is assumed to be the symbol. The 
predefined filelun SYSIN is used. 

Syntax A CEP filelun. 
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writeln 

Expression 



Function Required. This is the expression that is to 

be written to the specified f ilelun. 
Default None. 
Syntax A CTP expression (including a literal string) . 



Switches 



:editmode= 



: emmodif y= 



Function 

Default 
Syntax 



Function 

Default 
Syntax 



:numrecs= 


Function 




Default 




Syntax 


:recnum= 


Function 




Default 




Syntax 


:timeout= 


Function 




Default 




Syntax 



Specifies the edit mode to be used when 

writing. 

line. 

Type :editmode= followed by one of the 

following edit-mode values: 



line 



raw 



Specifies the modifiers to the edit mode 

switch. 

none. 

Type :enmodify= followed by any combination of 

the following modifiers, separated by commas 

(unique abbreviations are allowed) : 

forceowrite unlock 

Specifies the number of bytes to be written. 

The size of the expression. 

Type :nunrecs= followed by an expression. 

Specifies the psition in the file at which 

the operation is to be performed. 

Current record psition. 

Type :reanuaF= followed by an expression. 

Specifies how long the CEP must wait before 

canceling the operation. 

-1. This is essentially unending. 

Type :timeout= followed by an expression. This 

number is in 1/100 ths of a second. 
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writeln 



Examples 



writeLn fnam nysymb 

This command writes the data from the symbol mysymb to the file 
associated with the f ilelun fnam, A new-line character is written after 
the end of the symbol. 

writeln "This is a string to write" 

This command writes the given string to SYS$OUTRJT. A new-line character 
is written after the end of the symbol. 



Using Prompts 



None. 



Notes on Usage 



Writeln is generally used to access a data file from within a command 
file. 

A report of the status of this operation is sent to the logical name 
SYS$RESULT. A standard 3-line diagnostic message results for all errors 
except ERRREAELBOF (140) and ERRTIMEOUT (128) . 

Filelun symbols are distinct frcm symbols, label symbols, and procedure 
symbols, and can therefore have the same names as symbols of other types. 
Filelun symbols cannot be used in expressions. 
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writeln 



Related CEP Commands and Statements 



close Close a file specified by a f ilelun 

erf ile Create a file and associate a f ilelun with it 

open Open a file and associate a f ilelun with it 

openpipe Open a pipe associated with output from a previous command 

read Read from a file 

write Write a line to a file 



writeln -4 



Chapter 3 
System Manager's Reference 



This chapter describes modifications and new features that pertain to 
system management. 



Booting the System 

On systems equipped with SCSI disk or tape drives, the order of boot 
devices for default booting is SMD, SCSI, WD3. In other words, if an SMD 
controller is installed in the system, the boot ROMs will attempt to boot 
from drive 0A0 on the SMD controller. If that drive fails for any 
reason, or if there is no SMD controller present, the system will attempt 
to boot from the SCSI disk — if an SCSI host adapter is installed. Again, 
the system will attempt to boot from disk drive 0A0. If that drive fails 
for any reason, or if no SCSI host adapter is installed, the system will 
attempt to boot from the WPC controller, drive 0A0. 



NOTE: If an SMD controller is installed but there is no drive 0A0, the 
system may take up to 1.5 minutes before it determines there is no 
disk drive present. The delay is necessary to allow slow disks 
adequate time to spin up before continuing the boot process. 



If the system cannot boot from any of the default boot devices, or if you 
are using the universal boot, the menu of available drive types appears 
on the screen. This menu contains, among others, the following entries 
(if an SCSI host adapter is installed on the system) : 

DS - SCSI Disk Controller 
TS - SCSI Tape Controller 
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If you select either of these two options, a slightly different prompt 
ccmes up next. For all other devices, the next prompt is 

Drive #, Board # (d,b): 

But for the SCSI devices, the next prompt is 

Drive #, Type #, Board # (dtb) : 

The extra field (Type #) is used by the SCSI drivers to select the 
address of the device on the SCSI bus. Your response to this prompt 
should be the WMCS drive ID of the drive from which you want to boot. 
For example, if you want to boot from SCSI drive 1A0, you would type 1A0 
in response to the prompt. 

The default drive IDs for disks and tapes on the SCSI bus are as follows: 

Tape Name Drive IP. 

_ST0 0G0 

S11 0F0 



Disk Name 


Drive ID 


_5D0 


0A0 


_SD1 


1A0 


_SD2 


2A0 


_SD3 


3A0 


_SD4 


0B0 


_SD5 


1B0 


_SD6 


2B0 


_SD7 


3B0 


_SD8 


0C0 


_SD9 


1C0 


SD10 


2C0 


_SD11 


3C0 


_SD12 


0D0 


_SD13 


1D0 


SD14 


2D0 


SD15 


3D0 



In systems with the universal boot ROMs, the name of the boot device 
driver does not need to be accurately specified in the SYSCCNFIG. xxx file 
(edited by sysprof) , because the boot is automatically attempted from the 
SMD, SCSI, and WD3 controllers, as explained at the beginning of this 
section. However, the name of the boot device driver is still recorded in 
the SYSCCNFIG. xxx file so that systems with older ROMs will still work by 
using the name in the file. 
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TTY Networking 



You can now 6b pint-to-point networking using RS 232 serial connections 
across asynchronous TTY ports. Point-to-point means that computers can 
talk directly with other computers to which they have a direct TTYNET 
link. The full networking functionality implemented for ETHERNET is 
available on TTYNET, except that it is much slower. 

As far as speed goes f TTYNET is just slightly slower than usscopy when 
used for copying files, because TTYNET uses a much more comprehensive 
protocol to gain the increased reliability and functionality. 

TTYNET will run on any asynchronous I/O board supported by WICAT (i.e. 
080, 104, IPE and ICE boards). It is most efficient when running on IPE 
and ICE boards because much more of the interrupt overhead is handled by 
the boards. TTYNET does its extensive protocol processing at interrupt 
level 1, so it will not interfere with normal level 2 processing for 
other TTY I/O on normal ports. 

Multiple TTYNET links may be connected between the same two host 
computers. The TTYNET code will automatically detect that there are 
multiple links, and it will share them evenly when transferring data. 
TTYNET shares the links based on data width (7 or 8 bit) and baud rate. A 
9600-baud link will get twice as much data as a 4800-baud link. The 
protocol control packets will always be transferred on the fastest link. 
Only the data packets are split up across the multiple lines. This 
sharing of multiple TTYNET links adds a greater bandwidth to the data 
transmissions. However, adding more than 2-3 lines between two computers 
will probably not increase throughput. 

TTYNET runs reliably on slow, modem-speed lines (1200 baud), but it is 
very slow and should not be used for more than one virtual circuit 
connection at a time. Nbre than one circuit will work if the network 
activity is very light. But for instance, if the line is being used to 
transfer one 4-Kbyte packet on a virtual circuit and another user 
attempts to dial on a new virtual circuit over the same line, the 30- 
second built-in timeout on the dial will expire before the dial can be 
completed, because the dial and dial-response packets are queued up after 
the 4-Kbyte packet. 

TTYNET should run on 8-bit lines if at all possible. However it will 
support 7-bit data lines. During the initial configuration, and after 
transmission failures, small test-pattern packets are put out on the 
line. These test-pattern packets are used to determine the data width 
available on the line. If only 7 bits is reliable, the network code will 
enable both ends of the connection for 7 bit communication. 

Any TTY ports which you desire to use for networking must first be 
mounted using the normal TTY drivers. 
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You must also mount a generic TTYNET device, which will not be associated 
with any particular hardware or port. Only one of these generic devices 
can be mounted. This generic TTYNET device contains the network layer 
and datalink layer code, which implements the TTYNET protocol. To mount 
the TTYNET device, execute the following command: 

mnfc _ttynet 

Cnce the TTYNET driver is mounted and the appropriate RS 232 ports are 
also mounted, you can enable TTY networking on the RS 232 port ty 
executing the following command (where "portname" is the name of the 
port) : 

dstat "portname" rnetwork 

The foregoing command causes the TTY driver to dynamically link up with 
the TTYNET driver, and from that time forward the TTY driver will act as 
an I/O device for the TTYNET driver. 

As soon as a port is in network mode (enabled via dstat ) , it begins to 
periodically output configuration commands over the RS 232 line. When a 
remote terminal (on another node) begins to talk on the other end of the 
line, the two will "link up" with each other and exchange site IDs and 
nodenames. This process can take anywhere from 10 to 70 seconds, 
depending on when a network update packet occurs. Network update packets 
happen every minute, and the nodename exchange takes about ten seconds. 

When you want to turn a TTYNET port back into a normal TTY port, execute 
the following command (where "portname" is the name of the prt) : 

dstat "portname" rnonetwork 

The foregoing command causes the TTY driver to unlink from the TTYNET 
driver and return to normal operation. 

If you set a TTY port into network mode while the port is in use 
(currently open by a process) , the port will be marked internally as 
"network pending" and will remain in normal TTY mode until the port is 
idle (last process closes) , at which time the port will then switch into 
"network" mode. If a "network pending" port is set back into normal 
mode, the "network pending" state is cleared. This feature lets you dial 
into a remote machine, log on, set the remote port into network mode, and 
then log off. When you log off, the port will go into network mode. 

NOTE: The CXP does an implicit hangup on a modem line during log off. To 
prevent this, execute the following command: 

log :notaangup. 
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The "remote" bit of the device status flags (displayed or set with dstat) 
adds even more functionality. If the remote bit is set and a network 
connection loses its carrier (DSR drops) , or if the connection is broken 
for any reason, then the port will revert back to normal TTY mode. With 
the operation of this bit, you can call into a remote machine as 
described above and set the remote bit on that port (on the remote 
machine). Then when the connection is broken on the remote machine, the 
remote port will go back into normal TTY mode so someone else can call in 
and log on to it. 

When a port is put into network mode, it changes its class in the device 
table to TTYNET. One effect of this is that utilities such as dev and 
dstat will show that the device is a network device. Also, this prevents 
loqflush from trying to fork logon on the port. When a port returns to 
normal TTY mode, its class is changed back to what it was before entering 
network mode. 



Process Priority/Snapping 

Preemptive interrupts have been implemented on TTY devices. This means 
that if a process wakes up and its priority is higher than the priority 
of the process currently scheduled, the WMCS will immediately do a 
context swap to the process that just woke up. 

Preemptive interrupts are enabled by executing the dstat command with the 
: preempt switch. 



Print Queue 

All processes that are created by the QUO-GR will have the NCWATCHDOG 
attribute assigned. This way print jobs will not be killed by WATCHDOG. 



SCSI tapes 

The cartridge tape drives we are using for the SCSI tape subsystem are 
industry standard 0.25-inch streaming tape drives. They use the standard 
QIC-36 interface. This interface has several limitations compared to the 
standard 0.5-inch tape interface. 

The first limitation is that the tape drives will write only 512-byte 
fixed blocks on the physical tape media. In order to maintain seme 
compatibility with previous tape software, we simulate variable blocks in 
the driver software. To do that efficiently, we had to embed seme 
control information in the physical tape blocks and to require that the 
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block size be rounded up to the nearest 512-byte boundary, minus the 
space for the control information. That is why if a tape is initialized 
(with dinit ) with a block size of 1024 bytes f the actual block size is 
1018 bytes, or if it is initialized with a block size of 4096 bytes (a 
typical default) , the actual block size is 4084 bytes. The tape software 
does all the conversion from user-requested block sizes to the actual 
block sizes. A side effect of this special blocking is that no logical 
block skipping is supported. Any forward tape positioning within a file 
will have to be done using read commands. No reverse tape positioning 
will be allowed at this time. 

The second limitation is that these drives will not do reverse 
positioning themselves. Many utilities depend on the ability to skip 
back one or more files in order to reread them for various reasons. This 
requires that we simulate reverse file positioning in software. This can 
only be done by rewinding and then skipping forward the appropriate 
number of files to reach the desired location. This is reliable, but it 
is very slow. The slowness is particularly noticeable in the backup 
utility when using the rverify switch. We recommend that you not use 
:verify on SCSI tapes. 

The third limitation is that these drives will write data only at BOT 
(physical beginning of tape) or EDD (the logical end of data on the 
tape) . This means that to write on one of these tapes, you may only write 
at the end of the tape. To reuse a tape, you must reinitialize (with 
dinit ) it every time you wish to start writing at some location other 
than BOD. This is because of the write electronics in the tape drive, and 
the tape format. The tape drive does not overwrite blocks, and it erases 
data only when writing on the first track, but when it does erase, it 
erases the whole tape. This causes the entire tape to be erased when the 
first track is written. This is a generic limitation of the class of ID- 
track serpentine 0.25-inch cartridge tape drives. 



INDIE: Tapes made for the ADEI cartridge system are not compatible with 
tapes made for the SCSI system, and they cannot be interchanged. 
The SCSI cartridge drives require a different cartridge media (able 
to record at higher density) than does the ADEI. 



"fydra" Audio and Graphics 

The new device drivers that support the "Hydra" audio and graphics boards 
are /SYSDSH/HAB$100.DSR (audio) and /SYSDSIV'HGB$100.DSR (graphics). To 
make these new drivers transparent and to allow use of the old device 
names, logical names ( hydra $audio$driver for audio, hydra $gra phi cs$driver 
for graphics) are set to the appropriate driver names. A new command 
file, /SY3LIB/SETHYDRA. OOM, is called by /SYSLIB/DEVT CEUP.COM at boot 
time to determine which type of graphics and audio boards are present in 
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the system. SETHYDRA.COM sets the logical names for the drivers 
accordingly. To run "Hydra" graphics or "Hydra" audio on a WICAT- 
proprietary bus system (^sterns 2220 and 300), you must remove the 
exclamation mark (comment mark) from the following line in the file / 
SYSLIB/DEVICHJP. QDM: 

@sy s $di sk/sy si ib/se thy dr a 



Subdisk Devices 

A subdisk device is a file (on a disk) that "looks" (to the QP) like 
another disk. A subdisk can be created by executing the dinit command. 
After the subdisk is created, it can be mounted and dismounted with the 
mnt and dmnt commands respectively. Dismounting the subdisk will not 
cause the subdisk file to be deleted. 

When a subdisk device is initialized (with dinit) and the tformat switch 
is specified, the subdisk driver allocates space to the subdisk file for 
the device's maximum size. If the :format switch is not specified, the 
subdisk driver allocates space to the subdisk file only as it is needed. 

The name and size of the subdisk file can be determined the following 
ways: 

1. Using the sysprof command, you can specify the subdisk filename and 
the subdisk size. 

2. When you initialize a disk (using dinit ) , you can specify one or both 
of the following switches: 

:sutdkfname= 
:subdksize= 

These switches override the subdisk filename and subdisk size 
specified by sysprof . 

3. When you mount the disk (using mnt ) , you can specify the following 
switch: 

:subdkfname= 

This switch overrides the subdisk filename specified by sysprof . 

4. If the subdisk is not defined by any of the foregoing methods, the 
default filename of the subdisk will be SYS$DISK/ 
SYSDSR/"DEVNAME".DSK, where "DEVNAME" is the user-specified 
devicename. The maximum size of the subdisk will be determined by 
the :drivetype= switch (used with dinit) . 
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When a subdisk device is initialized (with dinit ) , a drive type must be 
associated with it. The possihle drive types for subdisks are SIBDISKA 
and SUBDISKB. Both define a subdisk of 512 Kbytes; SUBDISKA has a sector 
size of 0.5 Kbytes, and SUBDISKB has a sector size of 1 Kbyte. 

NOTE: You can specify the size of a subdisk only if the SUBDISKA or 
SUBDISKB drive type is used. 

When a subdisk is defined, you may use any of the drive type entries that 
are valid with the :drivetype= switch. This is useful if you want to 
build a copy of a smaller, slower disk on a larger, faster disk. You can 
define a subdisk using the appropriate drive type entry. Then you can 
mount the subdisk and build it up as desired. When the subdisk is 
complete, you can use the xfer command to copy the subdisk file directly 
to the physical device. Note that this can be done with any of the drive 
type entries. The only requirement is that the entire subdisk file must 
reside on the given volume. 

You may also take an existing device (like a floppy) and use xfer to copy 
the device to a file on a larger disk. 

A subdisk file does not need to reside on the same node that the device 
is mounted on. Since subdisks have their own local disk cache, access to 
subdisk files on remote machines is fast because the file system does not 
have to go across the network for all sectors that it may need. 

Subdisks can have a sector size of 0.5 Kbytes or 1 Kbyte. It is not 
necessary for the device that the subdisk file resides on to have the 
same sector size, but it is more efficient if it does. 



Driver Files 

The following driver files are new and can be used to configure your 
system: 

/SYSDSIV'BSCSxxx.DSR This driver used to be released as part of the 

FBTE product. It is now part of the WMCS because 
the driver is independent of the RBTE. This means 
that the RBTE will continue to work with the WMCS. 

/SY5DSIV'H£B$156.DSR This is a new "Hydra" audio device driver that 

runs on the WICAT multi-bus systems (Systems 1250, 
1255, and 1260) . 
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/SYSDSS/HGB$156.DSR This is a new "Hydra" graphics device driver that 

runs on the WICAT multi-bus systems (Systems 1250, 
1255, and 1260). 

/SYSDSS/SDISK$xxx.DSR This is the new SCSI disk device driver. 

/SYSDSIV'SrAH:$xxx.DSR This is the new SCSI tape device driver. 

/SY5DS$/9UBDK$xxx.DSR r^is is the new subdisk device driver. 

/SYSDSR/mNT$xxx.DSR This is a new driver that will support TTYNET 

networking. It works in conjunction with the 
TTY$xxx.DSR driver. 
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Chapter 4 
Programmer's Reference 



This chapter contains the description of SVCs that were modified since 
the last printing of the WMCS Programmer ' s Reference Manual (May 1985) : 
_getpcb, _hibern, _mount, _setf cb, _wake, and _write. It also includes 
descriptions of new SVCs that are not in the WMCS Programmer's Reference 
Manual. 
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_ btrnpid 

Translate a string with a pid f return a BIG logical name. 

Description: 

Given a logical name, return the BIG equivalent. The equivalent 
string can be up to 4 Kbytes in length. If no translation can be 
found, the equivalent is a copy of the original. 

When a translation for a name is found, the equivalent string will be 
translated again until one of the following occurs: 

- The equivalent does not translate into anything else. 

- The equivalent is defined in terms of itself, (a recursive 
definition is detected. 

- The equivalent has been translated 16 times. 

This feature allows logical names to be defined in terms of other 
logical names. 

Given a pid, searches the logical name table of the specified 
process. If the name is not found, continues searching in the 
logical name table of the parent of the specified process, and so on 
with the grandparents until either the name is found or there are no 
other parents. If it is still not found, it will search the system 
logical name table. 

Abbreviations are allowed in logical names. An asterisk (*) in the 
logical name is a marker that indicates the minimum string that is a 
recognized abbreviation of the logical name. For example, if the 
logical name is "PR*INr", a translation of any of the strings "PR", 
"PRI", "PRIN", or "PRINT" will return the equivalence. 

If there is more than one occurrence of a name, the first one found 
is used. (Note that there can be only one instance of a given name 
in a process's logical name table) 
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Related Privileges: 

none - Allows the translation of logical names with the logical 
name table of any process with the same owner id and group 
id (uic) as the calling process. 

group - Allows the translation of logical names with the logical 
name table of any process with the same group id as the 
calling process. 

world - Allows the translation of logical names with the logical 
name table of any process. 



Parameters 
pid 

lname 



A long word containing the process ID of the process whose 
logical name tables are to be used. refers to the 
current process, -1 refers to the parent of the current 
process. 

Address of a null terminated string containing the logical 
name to be translated. The maximum length of this string 
is 93 significant characters followed by a null. If this 
string is longer than 93 characters, the string is 
truncated, and no attempt is made to translate it. 

Address of an EQUIVSZ buffer to receive the equivalent 
string associated with the logical name. It can be up to 4 
Kbytes in length. If the buffer is to small to hold the 
string, the string will be truncated. If an error is 
detected, this buffer will remain unmodified. 



equivsz - Holds the size of the equiv string buffer in bytes. 

status - Address of a long word to receive the result of the 
operation. 



equiv 



Diagnostics: 

errinsufpriv 
errprcsnotfnd 



1) The process lacks the privileges required 

to perform the operation. 
7) The specified Drocess is not in the system 



;2) 



co peixunn cue u^iauiuu. 
The specified process is not 
process table. 
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See Also: 



_assign - Assign a logical name 

__gassign - Assign a global logical name 

_getbglb - Retrieve a BIG global logical name. 

__getblog - Retrieve a BIG logical name. 

_getglb - Retrieve a global logical name 

__getlog - Retrieve a logical name. 

_tranpid - Translate another processes logical name. 

_trans - Translate a logical name 



Assembler Calling Sequence: 



push 


pid 


push 


lname 


push 


equiv 


push 


equivsz 


push 


status 


jsr 


_btrnpid 



; value - process id 

;address - logical name 

;address - equivalent string 

;value - the size of the equiv buffer 

;address - result of operation 

/•translate another processes logical name 



C function declaration: 

/* translate another processes logical name */ 
long /* returns result of operation */ 

_btrnpid(pid f lname, equiv, equivsz) 

long pid; /* process id */ 

char lname [94]; /* logical name */ 

char equiv[4096]; /* equivalent string */ 

long equivsz; /* size of equiv buffer*/ 



Fortran Subroutine Declaration: 



I translate another processes logical name 
subroutine btrnpid(pid f lname, equiv, equivsz, status) 



integer *4 pid 
character*94 lname 
character*4096 equiv 
integer*4 equivsz 
integer *4 status 



process id 
logical name 
equivalent string 
size of equiv buffer 
result of operation 
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Pascal Procedure Declaration: 



procedure _btrnpid( 



{** translate another processes logical name} 



pid : 


longint; 


{** process id} 


lname 


string [93] ; 


{** logical name} 


var equiv 


: string [40 95]; 


{** equivalent string} 


equivsz 


: longint; 


{** size of equiv buffer} 


var status 


: longint; 


{** result of operation} 


external ; 
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Delete CPIR record 

Description: 

This svc is used to remove a file type from the system Create Process 
Indirection Record (CPIR) table. Once a file type is removed, users 
can no longer perform a _CRPROC svc call on a file of the given type. 

Eventually the WMCS will be modified to have a different CPIR list 
per process and the user can access the SYSTEM CPIR list with the 
special id of -3 in the low word, thus the reason there is a PID 
parameter. But the per process list has not been implemented yet so 
the low word of the PID must be -3 for this to work. The high word 
of the PID is the siteid of the node to delete from. A value of zero 
will delete from the current node. 

Related Privileges: 

none - The process is not allowed to delete CPIR records, 
operator- The process can delete any CPIR record. 

Parameters: 

pid - The low word of the PID must be -3. The high word of the 

PID is the siteid of the node to insert into. A value of 
zero will do it to the current node. 

f iletype- Contains the file type of the entry to delete. 

status - Address of a long word to receive the result of the 
operation. 
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Diagnostics: 

errinsuf priv 

errinvsiteid 

errnotimp 

erridxrange 



(1) The process lacks the privileges required to 
perform the operation. 

(8) The specified site id does not exist. 
(45) This item is not implemented yet. 
(56) The table ends before the specified occurrence. 



See Also: 



_getcpir - Get CPIR records. 
_inscpir - Insert CPIR record. 



Assembler Calling Sequence: 



push 


pid 


push 


f iletype 


push 


status 


jsr 


_delcpir 



;value - process id 

;value - file type 

;address - result of operation 

;delete CPIR record 



C Function Declaration: 



long 

_delcpir(pid, filetype] 

long pid; 

long f iletype; 



/* delete CPIR record */ 

/* returns result of operation */ 

/* process id */ 
/* file type*/ 



Fortran Subroutine Declaration: 



i delete CPIR record 
subroutine _delcpir(pid, filetype, status) 
integer*4 pid 1 process id 

integer *4 filetype 1 file type 
integer *4 status ! result of operation 



Pascal Procedure Declaration: 

procedure _delcpir( 

pid : longint; 

filetype: longint; 
var status : longint 

) ; external ; 



{** delete CPIR record} 

{** process id} 

{** file type} 

{** result of operation} 



delcpir-2 



_getbglb 

Get a BIG global logical name 

Description: 

Given an index into a system's global logical name table, returns the 
logical name and equivalence associated with that index. The 
translation of this logical name can be up to 4 Ktytes in length. 



Related Privileges: 

None. 

Parameters: • 

index - which entry in the logical name table is desired. 

siteid - Site id of the system whose global logical name table is 
being accessed. Zero (0) corresponds to the system on 
which the calling process is executing. 

lname - Address of a 94 byte buffer to receive the logical name. 
String will be null terminated (up to 93 valid characters 
plus a null) . If an error is detected, this buffer will 
remain unmodified. 

equiv - Address of an EQUIVSZ buffer to receive the equivalent 
string associated with the logical name. It can be up to 4 
Kbytes in length. If the buffer is to small to hold the 
string, the string will be truncated. If an error is 
detected, this buffer will remain unmodified. 

equivsz - Holds the size of the equiv string buffer in bytes. 

status - Address of a long word to receive the result of the 
operation. 
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Diagnostics: 

errprcsnotfnd 

errinvsiteid 
erridxrange 



(2) The specified process is not in the system 

process table. 
(8) The specified site id does not exist. 
(56) The table ends before the specified occurrence. 



See Also: 



_assign 
_btrnpid 
_gassign 
_getblog 
_getglb 
_getlog 
_tranpid 
trans 



Assign a logical name 

Translate another processes BIG logical name. 

Assign a global logical name 

Retrieve a BIG logical name. 

Retreive a global logical name 

Retrieve a logical name. 

Translate another processes logical name. 

Translate a logical name 



Assembler Calling Sequence: 



push 


index 


push 


siteid 


push 


lname 


push 


equiv 


push 


equivsz 


push 


status 


jsr 


_getbglb 



;value - index into the table 

;value - system id 

; address - logical name 

;address - equivalent 

;value - the size of the equiv buffer 

;address - result of operation 

; retrieve a global logical name 



C function declaration: 



long 

_getbglb( index, siteid, 

long index; 

long siteid; 

char lname [94] ; 

char equiv [4096] 

long equivsz; 



/* retrieve a global logical name */ 
/* returns result of operation */ 
lname, equiv, equivsz) 
/* index into the table */ 

system id */ 

logical name */ 

equivalent */ 

size of equiv buffer*/ 



/* 
/* 
/* 
/* 
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Fortran Subroutine Declaration; 



I retrieve a global logical name 
subroutine getbgl ( index, siteid, lname, equiv, equivsz, status ] 



integer *4 index 
integer*4 siteid 
character *94 lname 
character*4096 equiv 
integer *4 equivsz 
integer*4 status 



index into the table 

system id 

logical name 

equivalent 

size of equiv buffer 

result of operation 



Pascal Procedure Declaration: 



procedure _getbglb( 



index 
siteid 
var lname 
var equiv 

equivsz 
var status 
external ; 



longint; 
longint; 
string [93] ; 
string [40 95]; 
longint; 
longint 



{** retrieve a global logical name} 
{** index into the table} 
{** system id} 
{** logical name} 
{** equivalent} 
{** size of equiv buffer} 
{** result of operation} 
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Get a BIG logical names 

Description: 

Given an index into a given process's logical name table, returns the 
logical name and equivalence associated with that index. The 
translation of this logical name can be up to 4 Kbytes in length. 



Related Privileges: 

None - Allows retrieval of logical names from tables of processes 
with the same user and group id (uic) as the current 
process. 

group - Allows retrieval of logical names from tables of processes 
with the same group id as the current process. 

world - Allows retrieval of logical names from tables of any 
process in the system. 



Parameters: 

index - which entry in the logical name table is desired. 

pid - Process id of the process whose logical name table is being 

accessed. 0=current process, -l=parent process. 

lname - Address of a 94 byte buffer to receive the logical name. 
String will be null terminated (up to 93 valid characters 
plus a null) . If an error is detected, this buffer will 
remain unmodified. 
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equiv - Address of an EQUIVSZ buffer to receive the equivalent 
string associated with the logical name. It can be up to 4 
Kbytes in length. If the buffer is to small to hold the 
string, the string will be truncated. If an error is 
detected, this buffer will remain unmodified. 

equiv sz - Holds the size of the equiv string buffer in bytes. 

status - Address of a long word to receive the result of the 
operation. 



Diagnostics: 

errinsufpriv (1) The process lacks the privileges required to 

perform the operation, 
errprcsnotfnd (2) The specified process is not in the system 

process table, 
erridxrange (56) The table ends before the specified occurrence. 

See Also: 

_assign - Assign a logical name 

_btrnpid - Translate another processes BIG logical name. 

__gassign - Assign a global logical name 

_getbglb - Retrieve a BIG global logical name. 

_getglb - Retreive a global logical name 

_getlog - Retrieve a logical name. 

_tranpid - Translate another processes logical name. 

_trans - Translate a logical name 



Assembler Calling Sequence: 



push 


index 


push 


pid 


push 


lname 


push 


equiv 


push 


equiv sz 


push 


status 


jsr 


_getblog 



; value - index into the table 

;value - process id 

; address - logical name 

;address - equivalent 

;value - the size of the equiv buffer 

;address - result of operation 

; retrieve a logical name 
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C function declaration: 



/* retrieve a logical name */ 

long /* returns result of operation */ 

_getblog( index, pid f lname, equiv, equivsz) 

long index; /* index into the table */ 

long pid; /* process id */ 

char lname [94]; /* logical name */ 

char equiv [40 96]; /* equivalent */ 

long equivsz; /* size of equiv buffer*/ 



Fortran Subroutine Declaration: 



! retrieve a logical name 
subroutine getblo ( index, pid, lname, equiv, status) 



integer *4 index 
integer *4 pid 
character *94 lname 
character* 40 96 equiv 
integer *4 equivsz 
integer *4 status 



index into the table 

process id 

logical name 

equivalent 

size of equiv buffer 

result of operation 



Pascal Procedure Declaration: 



procedure _getblog( 



index 

pid 
var lname 
var equiv 

equivsz 
var status 
external ; 



longint; 
longint; 
string [93] ; 
string [40 95! 
longint; 
longint 



{** 

;** 
[** 
?•* 
;** 

?** 
/** 



retrieve a logical name} 

index into the table} 

process id} 

logical name} 

equivalent} 

size of equiv buffer} 

result of operation} 
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Get a CPIR record 

Description: 

This svc is used to obtain a list of CPIR records. Given an index 
into the system table of installed files, this call returns the 
corresponding entry, which is composed of a file type and a command- 
line string. 

Eventually the WMCS will be modified to have a different CPIR list 
per process and the user can access the SYSTEM CPIR list with the 
special id of -3 in the low word, thus the reason there is a RID 
parameter. But the per process list has not been implemented yet so 
the low word of the RED must be -3 for this to work. The high word 
of the PID is the siteid of the node to get the list from. A value 
of zero will look at the list on the current node. 

Related Privileges: 

None. 

Parameters : 

pid - The low word of the PID must be -3. The high word of the 

PID is the siteid of the node to insert into. A value of 
zero will do it to the current node. 

index - The index into the system table of the file type being 
requested. The first entry in the table has an index of 
zero. 

fstr - Address of a string to receive the command line string. The 
string may contain up to 93 significant characters and will 
be null terminated. 

f iletype- Address of a long word to receive the file type. 
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status - Address of a long word to receive the result of the 
operation. 



Diagnostics: 

errinvsiteid 

errnotimp 

erridxrange 



(8) The specified site id does not exist. 
(45) This item is not implemented yet. 
(56) The table ends before the specified occurrence. 



See Also: 



_delcpir - delete CPIR record. 
_inscpir - Insert CPIR record. 



Assembler Calling Sequence: 



push 


pid 


push 


index 


push 


fstr 


push 


f iletype 


push 


status 


jsr 


_getcpir 



;value - process id 

;value - index into table 

; address - receives command line 

;address - receives file type 

;address - result of operation 

;Get CPIR record 



C Function Declaration: 





/* 


long 


/* 


_getcpir(pid r index, fstr, 


filetype) 


long pid; 


/* 


long index; 


/* 


char fstr [94]; 


/* 


long *f iletype; 


/* 



get CPIR record */ 

returns result of operation */ 



process id */ 
index into table */ 
receives command line 
receives file type */ 



f / 



Fortran Subroutine Declaration: 



! get CPIR record 
subroutine getcpi(pid, index, fstr, filetype, status! 



integer *4 pid 
integer *4 index 
character *94 fstr 
integer*4 filetype 
integer *4 status 



process id 
index into table 
receives command line 
receives file type 
result of operation 
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Enseal Procedure Declaration: 



procedure _getcpir( 



pid 
index 
var f str 
var filetype 
var status 
) ; external ; 



longint; 
longint; 
string [93] ; 
longint; 
longint 



{** get CPIR record} 

{** process id} 

{** index into table} 

{** receives command line} 

{** receives file type} 

{** result of operation} 



getcpi r-3 



_getpcb 



Get process control block. 
Description: 



Given the process ID (PID) of a process in the system, copy the 
process control block (PCB) for that process into the buffer of 
the calling process, 

CAUTION: The format of the process control block may 
change with each release of the operating system. 
The current definition is included in each 
release in the file named /SYSINCL.SYS/PCBDISP.*. 
The name of the record is "pcbtable", i.e. in 
your program, you can declare a variable whose 
type is "pcbtable". 

The format of the PCB is as follows: 



Name 



pcbnextlink 

pcbbacklink 

pcbsysidnum 

pcbidnum 

pcbname 



Length 

(bytes) Description 



4 
4 
2 
2 
16 



Forward link to next pcb on same priority 

level 

Backward link to previous pcb on same 

priority level 

Gontains the system ID number (the most 

significant word of the PID) 

Gontains the least significant word of 

the PID 

The process name 
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pcbstatus 



A bit encoded long word representing the 
process status. If the bit is asserted (1), 
the corresponding status applies. 



Bit name 1 


3it # 



Description 


pcbsttcabort 


Process is to be 






scheduled for deletion 






(i.e. the next time 






this process is 






scheduled, send it to 






the delete process 






routines) 




1 


Reserved 


pcbsttohibernate 


2 


Process is to be 
hibernated 


pcbstabrin pr gs 


3 


Process is currently 
being deleted, (i.e. 
process is currently 
executing the delete 
process routines). 


pcbst exhinpr gs 


4 


Process is executing its 
exit handler 


pcbstrealtime 


5 


Process is in real time 
mode 


pcbstswapped 


6 


Process has been swapped 


pcbsthas child 


7 


Process is in a child 
wait state 


pcbstnocontc 


8 


Process may receive 
[CTRL] c without aborting 


pcbstr emcfcwai t 


9 


If set process is waiting 
on remote child process 


pcbst errreport 


10 


Process is reporting a 
system error 




11 


Reserved 


pcbst extndfcb 


12 


Process is extending the 
FCB.SYS file 


pcbstbadsecl og 


13 


Process is logging a bad 
sector 


pcbst ksam 


14 


Process is accessing a 
KSAM file 




15 


Reserved 


pcbst crprcs 


16 


Process is loading an 
image 


pcbst cleanup 


17 


Set when closing files 
while dying 


pcbstinque 


18 


Process is waiting in a 
queue 


pcbst crashdisp 


19 


If set, suppress crash 
displays 
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pcbtimeslice 



pctmathtype 



pcfcmathptr 

pcbprsize 

pcbprivilege 



pcbstalarmset 
pcbstsupervisor 



pcbstmulcrps 
pcbstdisperr 
pcbst tracing 
pcbstf ppending 
pcbsts ur ro ga te 
pcbstsurr child 



20 An alarm has been set 

21 The call was issued 
while the processor was 
in supervisor mode 

22 Multiple create process 
is in progress, 

23 If set, a crash report 
has been displayed 

24 If set, process is 
tracing 

25 If set, a floating point 
exception is pending 

26 If set, this is an NSP 
for networking 

27 If set, this is the 
child of a surrogate 

28-31 Reserved 



The process time slice value, i.e., the 
maximum amount of time (specified in .01 
milliseconds. That is, a time slice of 100 
represents 1 millisecond.) that the non-real 
time process will be allowed to run each 
time it is scheduled. 

The type of floating point hardware in use 
The valid types are: 

1 - skyl board 

2 - ndp2 board 

3 - ffpl board 

The math pointer. Contains the index of 

this process's window on the hardware floating 

point board. 

The number of pages of memory currently 

allocated to this process. Each page is 

4 Kbytes. 

The privileges granted to the current 
process. This is a bit encoded field. 
The privilege is granted when the 
corresponding bit is set. 



Bit Name 



Bit # Description 



pcbpvsetpriv 







pcbpvsystem 1 

pcbpvreadphys 2 



setpriv - Process may 
assign more privileges 
than it currently has. 
system - Process has 
system access to files 
readphys - Process can 
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pcbuserid 2 

pcbgroupid 2 

pcbchildpcbadr 4 

pcbparntpcbadr 4 

pcbcurpriority 2 

pcbalarmtime 8 



pcbpvw ritephys 

pcbpv set prior 
pcbpvchngsuper 

pcbpvbypass 

pcbpvoperator 

pcbp/altuic 



pcbpvworld 



pcbpvgroup 



10 



pcbpmetwork 11 

pcbp/setattr 12 

13-15 



do physical read 

operations to devices 

and memory 

writephys - Process 

can do physical write 

operations to devices 

and memory 

setprior - Process can 

increase the process 

priority 

chngsuper - Process 

can change to 

supervisor mode of 

execution 

bypass - Process can 

access files and 

devices independently 

of file protection 

operator - Process can 

perform operator 

functions 

altuic - Process can 

have access to files 

as though it had the 

same user and group i< 

(uic) as the owner of 

the process image 

world - Process can 

affect any process 

in the system 

group - Process can 

affect any process 

with the same group id 

as itself 

network - Process can 

do network accesses 

setattr - Process can 

modify its attributes 

Reserved 



most significant 
least significant 



The owner ID of the process 

word of the uic) 

The group ID of the process 

word of the uic) 

Address of the pcb for the child process of 

this process 

Address of the pcb for the parent process of 

this process 

The current priority level 

The date and time at which to issue the alarm 
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pcbtimeout 8 

pcbnondelcnt 2 

pcbcriticalcnt 2 

pcbusp 4 

pcbssp 4 

pcbevntfl 4 

pcbimgsiteid 2 

pcbattributes 2 



pcbimgdev seqnum 



Hie date and time at which the current 
operation will time out 
Non-delete count 
Critical code count 
The user stack pointer 
The system stack pointer 
The process event flags 
Site ID of the image file 

Attributes pertaining to the current process. 
This is a bit encoded field. The attribute is 
given when the corresponding bit is set. Note 
that these offsets are defined for being in 
the high order word of a longword. Because it 
is only a word in the PCB f if you access the 
PCB directly you will have to subtract 16 from 
these numbers. 



Bit Name 



Bit # Description 



pcbattrdesencrypt 16 If set, do network 

encryption with DES 
algorithm 

pcbattrfastencrypt 17 If set, do network 

encryption with fast 



pcbattruserl 
pcbattruser2 
pcbattruser3 
pcbattruser4 
pcba ttr nowat chcbg 



algorithn 

23 If set, user attribute 
bit 1 

24 If set, user attribute 
bit 2 

25 If set, user attribute 
bit 3 

26 If set, user attribute 
bit 4 

27 If set, cannot be 
killed by WATCHDOG 
utility 

pcbattrnotswappable 28 If set, cannot swap 

this process 
pcfcattrprezeromem 29 If set, pages are 

zeroed as they are 

allocated 
pctattrpostzeromem 30 If set, pages are 

zeroed as they are 

released 
pcbattrforceset 31 If set, other set bits 

will be set 

The mount sequence number of the device that 
contains the image file frcm which this 
process was initiated 
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pcbimgf cbnum 


4 


pcbimgseqnum 


2 


pcbstacktop 


4 


pcbpar abort sts 


4 


pcbexithdr 


4 


pcbabortreason 


4 


pcbiogi clink 


4 


pcblogicque 


4 


pcbdefdevadr 


4 


pcbdef dev seqnum 


2 


pcbdef f cbnum 


4 


pcbdef seqnum 


2 


pcbdef strl en 


2 


pcbdef diradr 


4 


pcbdef dirl en 


2 


pcbofpadr 


4 


pcbkpfdadr 


4 


pcbqueadr 


4 


pcbnetpcktnum 


2 


pcbtrapvecs 


64 


pcb0divide 


4 


pcbchktrap 


4 


pcbtrapv 


4 


pcbt race trap 


4 


pcblinel010 


4 


pcbiinellll 


4 


pcbdef exi thand 


4 


pcbfpinthand 


4 


pcbtrapreserved 


16 


pcbloaderaddr 


4 


pcbevntflque 


4 


pcbtrapreturn 


4 


pcbt rapi urn 


2 


pcrmailptr 


4 


pctmailque 


4 


pcbdef aultprot 


2 


pcbaltuserid 


2 


pcbaltgroupid 


2 


pcbhibercnt 


2 



pcbschedcnt 
pcrnsmaddr 



The PCB number of the image file from which 

this process was initiated 

The sequence number of the image file 

from which this process was initiated 

Address of the top of the system stack 

Address of where to put status in parent 

Address of the process's exit handler 

A code indicating why this process terminated 

Address of the logical name table for process 

Queue for linking logical names 

Address of the device table for the default 

device for this process 

The mount sequence number of the default 

device for this process 

PCB number for the current default directory 

sequence number for the current default 

directory 

Length of the default device string 

Address of the default directory string 

Length of the default directory string 

List head to open files 

List head to open KSAM files 

Address of the pcb of next entry in 

whatever queue this process is waiting 

Network packet number 

Trap handler addresses 

Divide by zero trap handler address 

Check trap handler address 

Overflow trap handler address 

Trace trap handler address 

1010 emulation trap handler address 

1111 emulation trap handler address 

Define exit tran handler 

Floating point interrupt handler 

Reserved space for future trap handlers 

Address of loader routine 

Queue for event flag synchronization 

Trap return address 

The current trap number 

Address of the head node for pending mail 

Queue for processes waiting for mail 

The default protection mask 

The user ID number of the "image file 

The group ID number of the image file 

Gount of how many times this process has been 

hibernated 

Cbunt of how many times this process has been 

scheduled. 

List head for named shared memory regions 

that are currently mapped into this process 
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pcbnetpageaddr 4 

pcrml drl isthead 8 

pcballochdr 4 

pcborigprivilege 2 



pcbdefaultnode 4 

pcbcurtrapnum 4 

pcbcurtrapprm 4 

pcbremotepid 4 

pcbremoteuic 4 

pcbr enotepr iv 2 

pcbrctadr 4 

pcbbasepriority 2 

pcbcur state 4 



pcbswapt slice 


2 


pcbr emotetsl ice 


! 2 


pcbremoteattr 


2 


pcbr emotepr ior 


2 


pcbnoswapcnt 


2 


pcbpagecnt 


2 


pcbreserved 


16 


pcbidf ield 


2 


pcbidtag 


$3333 


pctmemory 


1024 


pcbdevstr 


94 



Holds network packet page address 

List head for control information fcy various 

WMCS loaders. 

List head for devices that are allocated to 

this process 

Holds original privileges process was created 

with before any installed privileges were 

added in, 

Gontains siteid of current default node 

The number of current SVCs being executed 

The stack address of current trap parameters 

If this is an NSP, this is FID of originator 

If this is an NSP, this is UIC of originator 

If this is an NSP, this is priv of originator 

List head for remote connection table 

Holds base priority level 

Index into scheduling queues for current state 

Queue Name Offset Description 



pcbcst_toswapin 

pcbcst_active 4 

pcbcst_asleep 8 

pcbcst_J.cwait 8 

pcbcstjiibernate 12 

pcbcst_childwait 16 

pcbcst__sqsize 20 



List for processes to 

be swapped in 

List for active 

processes 

All processes above 

here are in normal 

sleeps 

List for processes 

in I/O wait 

List for processes 

in hibernation 

List for processes 

in child wait 

Holds size of this 

scheduling queue 



Holds # of timeslices allocated to the 

process after it is swapped in, before it 

is eligible to be swapped out again 

If this is an NSP, timeslice of originator 

If this is an NSP, attributes of originator 

If this is an NSP, priority of originator 

If non-zero, process is swap critical 

Holds size of this pcb in pages 

Reserved space 

Table ID tag value 

Table ID value 

The process's memory mapping registers 

The default device/directory string 
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Related Privileges 
None. 



Parameters : 

pid 

pcbuff 

len 

retlen 

status 



- Process ID of the process whose PCB is desired. 

- Address of the buffer to receive the PCB 

- The number of bytes requested. This number of 
bytes will be copied into the users buffer. 

- Address of where to return the number of bytes 
actually copied into the users buffer. 

- Address of a long word to receive the result of 
the operation. 



Diagnostics: 

errinsufpriv 
errprcsnotfnd 

See Also: 



(1) The process lacks the privileges required to 
perform the operation. 

(2) The specified process is not in the system 
process table. 



_gengy - Get PID of ancestor process 

_getpid - Get process ID (PID) from name 

_getpiam - Get process name from PID 

__prclst - Get PEDs on a priority level 



Assembler Calling Sequence: 



push 


pid 


push 


pcbuff 


push 


len 


push 


retlen 


push 


status 


jsr 


_getpcb 



;value - process id 
;address - buffer to receive pcb 
; value - length of buffer 
;address - # of bytes transferred 
;address - result of the operation 
;get process control block 
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C Function Declaration: 



tinclude "sy s$disk/sysincl . sys/pcbdisp. h" 

/* get process control block */ 

long /* returns result of the operation */ 

_getpcb(pid, pcbuff, len, retlen) 

long pid; /* process id */ 

pcbtahle *pcbuff ; /* buffer to receive pcb */ 

long len; /* length of buffer */ 

long *retlen; /* # of bytes transferred */ 



FORERAN Subroutine Declaration: 

c ! get process control block 

subroutine _getpcb(pid, pcbuff, len, retlen, status) 
integer *4 pid I process id 

character* (*) pcbuff ! buffer to receive pcb 
integer *4 len I length of buffer 

integer*4 retlen ! # of bytes transferred 
integer *4 status I result of the operation 

Eascal Procedure Declaration: 

% %sy s $di sk/sy sincl . sy s/pcbdi sp. pas 

procedure _getpcb( {** get process control block} 



pid 
pcbuff 
len 
var retlen 
var status 
) ; external ; 



longint; {** process id} 

~array_of_char; {** buffer to receive PCB} 
longint; {** length of buffer} 

longint; {** # of bytes transferred} 

longint {** result of the operation} 
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Hibernate a process. 

Description: 

Remove a process from consideration by the scheduler. This 
will increment a hibernate reference count and set the 
hibernate status bit so the process can no longer be scheduled. 
There are two ways to wake a hibernated process. A call to 
_wake will set the reference count to zero and clear the 
hibernate status bit. On the other hand a call to _wakec will 
decrement the hibernate count and clear the hibernate status 
bit when the count goes to zero. A hibernated process will 
exist indefinitely in the process table but in a dormant state 
until either the process is terminated by another process, or 
is awakened by another process. 

Related Privileges: 

none - Allows process to hibernate any process with the same 
owner id and group id (uic) as the calling process. 

group - Allows process to hibernate any process with the same 
group id as the calling process. 

world - Allows process to hibernate any process in the 
system. 

Parameters : 

pid - This is a long word uniquely specifying the process 

ID of the process to be hibernated. The high word 
refers to the site ID, with representing the node 
you are on. The low word refers to the process: 
refers to the calling process, -1 refers to the 
parent of the calling process, -2 is undefined, and 
-3 hibernates all processes except the calling 
process. 

status - Address of a long word to receive the result of the 
operation. 
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Diagnostics : 

errinsufpriv 
errprcsnotfnd 

See Also: 



(1) The process lacks the privileges required 
to perform the operation. 

(2) The specified process is not in the system 
process table. 



_wait - Pause for a period of time 

_wake - Wake a hibernated process 

_wakec - Wake a hibernated process with count 



Assembler Calling Sequence: 



push 


pid 


push 


status 


jsr 


_hibern 



C function declaration: 



long 
_hibern(pid) 

long pid; 

Fortran Subroutine Declaration: 



; value - process id 

;address - result of the operation 

;hibernate a process 



/* hibernate a process */ 

/* returns result of the operation */ 



/* process id */ 



! hibernate a process 
subroutine hibern(pid, status) 



integer *4 pid 
integer *4 status 

Pascal Procedure Declaration: 

procedure _hibern( 

pid : longint; 

var status : longint 
) ; external ; 



! process id 

! result of the operation 



{** hibernate a process} 

{** process id} 

{** result of the operation} 
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Insert a CPIR record 

Description: 

Allows a process to insert a Create Process Indirection Record (CPIR) 
into the system list. If a record already exists of the given file 
type, the old record is deleted first. 

This record consists of a file type and a string. If a user does a 
_CREROC svc on a file that is not an image type file, then the WMCS 
scans the CPIR records for the given file type. If a CPIR record 
exists for it, then the given string is inserted in front of the 
current command line. A new image file name is located by scanning 
the new command line string for the first invalid filename character, 
all characters before it are assumed to be the new image name. 

This operation is recursive in that the new image file will be 
located and if necessary the CPIR table will be scanned again. 

Eventually the WMCS will be modified to have a different CPIR list 
per process and the user can access the SYSTEM CPIR list with the 
special id of -3 in the low word, thus the reason there is a FID 
parameter. But the per process list has not been implemented yet so 
the low word of the FID must be -3 for this to work. The high word 
of the PID is the siteid of the node to insert into. A value of zero 
will insert into the current node. 



Related Privileges: 

none - The process cannot successfully insert a new file type into 
the CPIR list. 

operator- Allows the calling process to insert a new file type into 
the CPIR list. 
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Parameters 
pid 

fstr 



- The lew word of the PID must be -3. The high word of the 
FID is the siteid of the node to insert into. A value of 
zero will do it to the current node. 

- Contains the command line string to be inserted inf ront of 
the users command line. 



filetype- Contains the file type associated with the given command- 
line string. 

status - Address of a long word to receive the result of the 
operation. 



Diagnostics: 

errinsufpriv 

errinvsiteid 

errnotimp 



(1) The process lacks the privileges required to 

perform the operation. 
(8) The specified site id does not exist. 
(45) This item is not implemented yet. 



See Also: 



_delcpir - delete CPIR record. 
_getcpir - Get CPIR records. 



Assembler Calling Sequence: 



push 


pid 


push 


fstr 


push 


filetype 


push 


status 


jsr 


_inscpi r 



;value - process id 

;address - command line string 

;value - file type 

;address - result of operation 

; insert CPIR record 



C Function Declaration: 



long 

_inscpir(pid, fstr, filetype) 

long pid; 

char fstr [94]; 

long filetype; 



/* insert CPIR record*/ 

/* returns result of operation*/ 

/* process id*/ 

/* command-line string*/ 

/* file type*/ 
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Fortran Subroutine Declaration: 

c ! insert CPIR record 
subroutine inscpi(pid, fstr, filetype, status) 

integer *4 pid I process id 

character *94 fstr ! command-line string 

integer *4 filetype I file type 

integer*4 status ! result of operation 

Pascal Procedure Declaration: 

procedure _inscpir( {** insert CPIR record} 

pid : longint; {** process id} 

fstr : string[93]; {** command line string} 

filetype: longint; {** file type} 

var status : longint {** result of operation} 

) ; external; 
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Mount a logical device. 

Description: 

This system call is used to announce the existence of a device 
to the system. The system then mounts the device by loading a 
driver and initializing the device. If the device driver is 
already present in memory, a new one is not loaded; rather, the 
current driver is shared. 

For disk and tape class devices which are not mounted 
"special ", the owner of the volume and the protection 
specification for each class of user is specified in the volume 
label. 

For TTY, pipe and sync class devices, the owner of the device 
becomes the UIC of the process issuing the call to _mount. The 
protection mask for the device will be the default protection 
mask associated with the calling process. 

For devices mounted "special", the owner of the device becomes 
the UIC of the process issuing the call to _mount. The 
protection mask for the device will be the default protection 
mask associated with the calling process. 

The process must have read privilege to the device containing 
the device driver, execute privilege to all directories in the 
path to the device driver, read privilege to the directory 
containing the device driver and read privilege to the file 
containing the device driver. 

If the process has operator privilege, it can mount a device 
using a device driver that is not installed. If the process 
does not have operator privilege, it can only mount devices 
using installed device drivers. In either case, the process 
must satisfy the following requirements. 
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If the driver is specified by fcb.seq number, the process must 
have read privilege to the device containing the driver and 
read privilege to the file containing the driver. 

In addition, the process must have execute access to the device 
being mounted according to the owner and group ID (UIC) of the 
volume and its protection mask. Note that any process can mount 
a TTY, pipe or sync class device. 

The process must have operator privilege in order to mount any 
device as "special " (diskspc, ttyspc, etc.). 



Related Privileges: 

none - Allows mounting of device if the process has 

privileges as described above and the driver has 

been installed, 
altuic - Allows mounting of device if the owner of the image 

file of the current process has access to the file 

and device as described above. 
bypass - Allows mounting of device independent of the file 

protection, 
operator - Allows mounting of devices as 'special'. Also 

allows mounting devices with uninstalled drivers, 
system - Allows mounting of device if the system has access 

to the file and device as described above. 



Parameters : 
dname 



driver 



— This parameter consists of two components, 
separated by commas. The first component is the 
devicename. The second component is the drive ID. 
Address of a null terminated string containing the 
name by which the device will be known. This 
string will be translated automatically by the WMCS 
to its logical equivalent. This string may contain 
up to 93 valid characters followed by a null. 

- Address of a null terminated string containing the 
name of the file which contains the device driver. 
If a driver with' the same identifier (irrespective 
of file name) is found in the system, the driver is 
not loaded. This string will be translated 
automatically by the WMCS to its logical 
equivalent. This string may contain up to 93 valid 
characters followed by a null. 
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class 



- The device class. Valid classes are: 



0,1 - Character class device (TTYSpecial, 
TTY) 

2,3 - Tape class device (TapeSpecial, 
Tape) 

4,5 - Disk class device (DiskSpecial, 
Disk) 

6,7 - Network class device 
(NetworkSpecial, Network) 
8,9 - Pipe class device (PipeSpecial, 
Pipe) 

10,11- Sync class device (SyncSpecial, 
Sync) 

12,13- Queue class device 
(QueueSpecial, Queue) 
14,15- Nondev class device 
(NondevSpecial, Nondev) 



dstat 



The address of a 128 byte buffer containing the 
initial device status to be assigned the device 
when it is mounted. If this parameter is zero the 
default device status is used. 



This parameter has two purposes: 



2) 



To provide an opportunity to set device 
characteristics that, unless set properly, would 
not allow the device to be mounted, e.g., the 
tape block size. 

To set device characteristics that could 
otherwise not be changed once the device is 
mounted, e.g., disk cache size. 



This parameter is not meant to be a substitute for 
_setdst. As such, not all of the values that can 
be specified with _setdst can be specified in this 
parameter. 

The device status table is divided into two parts. 
The first half is device independent and is 
composed of the following, fields: 



Name 
dsclassid 

dsdriverid 



Length 

(bytes) Settable Description 



No The device class. Uses the class 
parameter to the _mount system 
call. 

No Unique ID number for this device 
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dsblksz 



dsharderr 


2 


device 




dssof terr 


2 


device 




dsreacbper 


4 


device 




dswriteoper 


4 


device 




dsmaxnumdev 


2 


dscurnumdev 


2 



dsnumtoretry 



dserrorreason 4 

error 

dsreserved 30 

dsnexttableptr 4 

table 



driver 
Yes block size of the device, e.g., 
sector size. For disks, the sector 
size is either 512 bytes or 1024 
bytes, determined by the driver. 
Note that disk sector size cannot 
be changed. For tapes, the default 
is 1024 bytes. Specify zero to 
accept the default. 
No The hard error count for the 

No The soft error count for the 

No Number of read operations on this 

No Number of write operations on this 

No Maximum # of devices this driver 
can handle 
No Number of devices currently 
mounted using this device driver 

Yes Number of times to retry before 
reporting a hard error. The 
default is determined by the 
driver. Specify zero (0) to accept 
the default. 

No Hardware error code for the last 

No Reserved 
No Address of next device status 
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The second half of the device status table is 
device class dependent. Bbr TATE class devices the 
second part is defined as follows: 



Name 

dstpstatus 
dstpflagsl 



Length 

(bytes) Settable Description 



No 
Yes 



Tape device status 

Tape status information. Bit encoded. If 

zero is specified, the default is used. 



Bit name 



dstpdoraw 



dstpreadahead 



dstperrintenb 



bit # Description 

0=Read after 
write disabled 
l=Read after 
write enabled 

1 0=Read ahead 
enabled 
l=Read ahead 
disabled 

2 0=Error interrupts 
are enabled 
l=Error interrupts 
are disabled 



dstpspeed 



Yes Tape speed - Specify zero to use default 



dstpdensity 



dstpspeedl2ips 1 
dstpspeed25 ips 2 
dstpspeed30ips 3 
dstpspeed50ips 4 
dstpspeed90ips 5 
dstpspeedl00ips 6 
dstpspeedl25ips 7 



Reserved 
12 ips 
25 ips 
30 ips 
50 ips 
90 ips 
100 ips 
125 ips 



Yes Tape density - Specify to use default 



dstpdens800bpi 1 
dstpdensl600bpi 2 
dstpdens3200bpi 3 
dstpdens6250bpi 4 
dstpdens6400bpi 5 



- Reserved 

- 800 bpi , 
-1600 bpi 

- 3200 bpi 

- 6250 bpi 

- 6400 bpi 



dstpiopbcnt 



Yes Number of IOIBs allocated to the 
drive. The default is determined 
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dstpcachesz 



dst preserved 
dstpuserf ield 



46 
8 



Yes # 



No 
Yes 



by the driver. Specify zero to use 
the default 

of sectors in disk cache. 
Default- is determined by the value 
in the boot block. Specify to 
use the default. 
Reserved 

User defined status. The default 
is determined by the driver. 
Specify zero to use the default. 



For DISK class devices the second half of the 
device status table is defined as follows: 



Nane 



Length 
(bytes) Settable Description 



dsdkintf ac 
dsdkiopbcnt 


2 
2 


No 
Yes 


dsdknumbsect 

dsdksectrack 

dsdkheads 

dsdkcylinders 

dsdkflagsl 

dsdkcurcyl 

dsdkcachesz 


4 
2 
2 
2 
2 
2 
2 


No 
No 
No 
NO 
No 
NO 
Yes 


dsdkentryname 
dsdkreserved 
dsdkuserf ield 


16 

20 

8 


No 
No 
Yes 



Disk interleave factor 

Number of IOPB's allocated to the drive 

The default is determined by the driver 

Specify zero to use the default 

The number of sectors on the volume 

The number of sectors on a track 

The number of heads on the device 

The number of cylinders on the volume 

Disk status information. Bit encoded word 

Current cylinder position 

# of sectors in disk cache. Default is 

determined by the value in the boot 

block. Specify to use the default. 

The name of the drive type 

Reserved 

User defined status. The default is 

determined by the driver. Specify zero 

to use the default. 



For TTY class devices the second half of the device 
status table is defined as follows: 



Name 



Length 

(bytes) Settable Description 



dstymoderegl 


1 


No 


dstymodereg2 


1 


No 


dstycmdreg 


1 


No 


dstytermtype 


1 


No 


dstystatreg 


1 


No 


dstypacketterm 


1 


No 


dstyflagsl 


2 


No 


dsty input cnt 


2 


No 



Uart mode register 1 

Uart mode register 2 

Uart command register 

Terminal type definition 

Uart status register 

Packet termination conditions 

Terminal status information 

Characters in input interrupt buffer 



dstyoutptcnt 2 

dstycolunnpos 2 

dstyinbufsz 2 



dstyoutbufsz 



dstywidth 2 

dstylength 2 

dstysubreadoper 4 

dstysubwriteoper 4 

dstyreserved 26 

dstyuserf ield 8 
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No Characters in output interrupt buffer 

No Current colunn position 

Yes Input buffer size in bytes. The default 

is determined by the driver. Specify 

zero to use the default. 
Yes Output buffer size in bytes. The default 

is determined by the driver. Specify 

zero to use the default. 
No Holds terminal width 
No Holds terminal length 
No Holds sub-read operations count 
No Holds sub-write operations count 
No Reserved 
Yes User defined status. The default is 

determined by the driver. To use the 

default, specify zero. 



For FIFE class devices the second half of the device 
status table is defined as follows: 



Name 



Length 
(bytes) Settable Description 



dsppreaderpid 


4 


No 


dsppwriterpid 


4 


No 


dspppipeid 


4 


No 


dsppbuffersz 


2 


No 


dsppbuffercnt 


2 


No 


dsppreadque 


4 


No 


dsppwriteque 


4 


No 


dsppreserved 


32 


No 


dsppuserf ield 


8 


Yes 



Process ID of pending reader 

Process ID of pending writer 

The pipe's ID 

The buffer size in bytes 

Number of characters in the pipe buffer 

Address of read queue 

Address of write queue 

Reserved 

User defined status. The default is 

determined by the driver. Specify zero 

to use the default. 



For SYNC class devices the second half of the device 
status table is defined as follows: 



Name 



Length 
(bytes) Settable Description 



dssymoderegl 


1 


No 


dssymodereg2 


1 


No 


dssycmdreg 


1 


No 


dssytermtype 


1 


No 


dssystatreg 


1 


No 


dssynumbsync 


1 


No 


dssyflagsl 


2 


No 


dssy input cnt 


2 


No 



Mode register 1 of the uart 

Mode register 2 of the uart 

Command register of the uart 

Terminal type definition 

Status register of uart 

Number of sync characters to write 

Device Status flags. Bit encoded. 

Nunber of characters in input interrupt 

buffer 
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dssyoutputcnt 


2 


No 


dssyinbufsz 


2 


Yes 


dssyoutbufsz 


2 


Yes 


dssyprevrderr 

dssyprevwrerr 

dssyprev retype 

dssynumbtrpad 

dssyrecsize 

dssyreserved 

dssyuserf ield 


4 
4 
1 
1 
2 
28 
8 


No 
No 
No 
No 
No 
No 
Yes 



Number of characters in output interrupt 

buffer 

Input buffer size in bytes. The default 

is determined by the driver. Specify zero 

to use the default. 

Output buffer size in bytes. The default 

is determined fcy the driver. Specify zero 

to use the default. 

Error from previous unverified read 

Error from previous no-wait write 

Type of previous read 

Number of trailing pads to write 

Used in transparent mode with ZEBs 

Reserved 

User defined status. The default is 

determined fcy the driver. Specify zero 

to use the default. 



For NEWORK class devices the second half of the device 
status table is defined as follows: 



Name 



Length 
(bytes) Settable Description 



dsnkflags 



No 



Device status flags. Bit encoded. 
Bit Name Bit # Description 



dsnkfcyte 
dsnkmodemctrl 



0=datagram mode 
l=byte mode 
0=not enabled 
l=modem Ctrl enabled 



dsnkwindowsize 1 No 

dsnkreserved 53 No 

dsnkuserfield 8 No 



Window size the circuit will use 

Reserved 

User defined status 



Bbr NCNDEV class devices the second half of the device 
status table is defined as follows: 



Name 



Length 

(bytes) Settable Description 



dsnduserf ield 



64 



No 



User defined status 



mount-8 



_mouit 



Name 



For QUEUE class devices the second half of the device 
status table is defined as follows: 

Length 

(bytes) Set table Description 



dsquassocdev 


9 


dsqusenddev 


9 


dsquf ormname 


10 


dsqunumexec 


2 


dsqucurnumexec 


2 


dsquflags 


2 



dsqulength 
dsquwidth 

dsqunextentry 

dsqutype 



dsqubaseprior 

dsqureserved 
dsquuserf ield 



1 
20 



No 



No 



No 



No 



No 



Yes 



No 

No 

No 
Yes 



No 

No 
No 



A null terminated string containing the 

name of the physical printer device 

A null terminated string containing the 

name of the physical device that control 

messages are to be sent to 

A null terminated string containing the 

current form name 

This is the maximum number of entries 

that can execute concurrently 

This is the number of entries that are 

currently active 

Device Status flags. Bit encoded. 



Bit Name 



Bit # Description 



dsqufl updating 



dsquflqmstay 



dsquflnorestart 2 



Updating current 
queue control 
file 

Queue manager 
process will 
remain running 
even when the 
queue is empty 
When the queue 
is mounted it 
does not restart 
jobs in queue 



Holds the length of the forms of the 
printer associated with this queue 
Holds the width of the forms of the 
printer associated with this queue 
Entry number of the next entry queued 
The type of queue this is. Values are: 



Value Name 

dsqutpprint 
dsqutpj ob 



Value Description 



Print type queue 
Job entry queue 



Priority that entries will be queued at 

if they specify the default priority 

Reserved 

User defined status 
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label 



status 



- Address of a 17 -byte string to receive the device 
label. The returned string will be null terminated 
(up to 16 valid characters and a null) . 

- Address of a long word to receive the result of 
the operation. 



Diagnostics: 




errinsufpriv 


(1) 


errnomemavail 
errinvdevnam ( 


(7) 
130) 


errundevnam ( 


131) 


errf ilnotfnd 
errreadLock ( 
errreadleof ( 


133) 
135) 
140) 


errnoexecpriv ( 


143) 


errnoreadpriv ( 


144) 


errinvfnstr ( 
errinvdirfle ( 


147) 
148) 


errinvdirstr ( 


149) 


errimprcmnt 
errinvcloper ( 


,164) 
173) 


errdirnotfnd ( 
errdevnamexs 
errinvclass ( 


177) 
179) 
180) 


errnobbfound 
errinvdnreq 


181) 
183) 


errno class 


(185) 


errprevinit 


(188) 


errmntasync 


(190) 


errmntsync 


(191) 


errinvdriver 


216) 


errdevwrtprot 
er r cantr eadds r 


(269) 
(308) 
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The process lacks the privileges required to 

perform the operation. 

All available memory has been allocated. 

The specified devicename is syntactically 

incorrect. 

The WMCS does not recognize the devicename. 

Is the device mounted? 

The specified file could not be found. 

The specified file is read-locked. 

The process tried to read past the logical end 

of a file. 

The process does not have Execute Privilege for 

the file. 

The process does not have Read Privilege for 

the file. 

The specified filename is syntactically incorrect, 

The specified directory is not a directory 

type file. 

The specified directory name is syntactically 

incorrect. 

This device was improperly dismounted. 

The operation is inappropriate for the 

device class. 

The specified directory does not exist. 

The specified device is already mounted. 

The WMCS does not recognize the specified 

device class. 

The specified volume has no valid boot block. 

The process requested more than 3964 bytes 

of dynamic memory. 

The device class handler was not loaded when 

the system was booted. 

The specified device is already mounted, and 

has another name. 

The specified device has already been mounted 

for synchronous use. 

The specified device has already been mounted 

for asynchronous use. 

The specified file does not contain a device 

driver. 

The specified device is write- protected. 

The size of the device driver does not match 
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its expected size, 
errinvdrvnum (311) A value in at least one field of the devicename 

is disallowed, 
errnohardware (312) The PC board for the specified device is not 

installed. 

Device integrity errors 

See Also: 

_dismnt - Dismount a logical device 
_£Lush - Blush I/O buffers to the device 
_getdnam- Get devicename 
_getdst - Get device status 
_giodst - Get device status with lun 
_setdst - Set device status 
_siodst - Set device status with lun 

Assembler Calling Sequence: 

% %sy s $di sk/sy sincl . sy s/dsta tdi sp. asm 

push dnane ;address - devicename 

push driver ;address - driver file name 

push class ;value - device class 

push dstat ;address - initial device status 

push label ;address - device label 

push status ;address - result of the operation 

jsr _mount ;mount a logical device 

C Function Declaration: 

#include "sy s$disk/sy sincl . sys/dstatdisp. h" 

/* mount a logical device */ 

long /* returns result of the operation */ 

_mount(dname, driver, class, dstat, label) 

char dname[S4]; /* devicename */ 

char driver [94]; /* driver file name */ 

long class; /* device class */ 

devicestatus *dstat; /* initial device status */ 

char label [17]; /* device label */ 
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FORERAN Subroutine Declaration: 



! mount a logical device 
subroutine mount (dname, driver, class, dstat, label, status' 
character* 94 dname 
character *94 driver 
integer *4 class 
character* (*) dstat 
character* 17 label 
integer *4 status 



devicename 

driver file name 

device class 

initial device status 

device label 

result of the operation 



i&scal Procedure Declaration: 



Note - If passing a device status block, use the following 
expression : cast (vloc (device status) ,longint) 

%%sy s$disk/sy sincl . sy s/dstatdisp. pas 



procedure _mount 
dname 
driver 
class 
dstat 
var vlabel 
var status 
) ; external ; 



{** mount a logical device} 

string[93]; {** devicename} 

string [93]; {** driver file name} 

longint; {** device class} 

longint; {** initial device status} 

string [16]; {** device label} 

longint {** result of the operation} 
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Write file control block. 

Description: 

This SVC allows the calling process to update the file control 
block for an open file on any disk class device. Note that this 
requires that the calling process have writephys privileges and 
have write access to the file for most fields, however, you can 
change the following fields without any privileges: 
fcbfiletype, fcbrecordsz, fcblogicalsz, fcbfileid, and 
fcbprotect. For security reasons the file should have been 
opened with write locked access. 

CAUTION: The FCB file is the heart of the file system. 
Careless tanpering with the FCB file can cause 
severe damage to the file system's integrity. 



NOTE: The format of the file control block may change with 
each release. The current definition is included in 
each release in the file /SYSINCL.SYS/FCBDISP.*. The 
name of the FCB record is "f cbtype, " i.e., in your 
program you can declare a variable whose type is 
"f cbtype. " 



There are several variations on the format of file control 
blocks, depending on the class of device which contains the 
file. Disk files contain "primary" FCBs and "continuation" 
FCBs. Tape files have "tape" FCBs. All other files have "tty" 
FCBs. You can only set the FCB for disk class devices. 
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The format of the first 14 bytes of the PCB record is the same 
for all types of FCBs. The format of this common type is: 



Name 



Length 

(bytes) Description 



fern urn 



febseqnum 



febcontf ctnum 



febcontfebseq 



febusageid 



FCB number for this FCB. The record 
number of this record within the PCB 
file. For tty FCBs, the value of this 
field is zero. This field may not be 
changed. 

FCB sequence number. This number is 
unique for each usage of this FCB. For 
tty FCBs,. the value of this field is 
zero. This field may not be changed. 
FCB number of continuation FCB. The 
record number of the next FCB for this 
same file. For tape and tty FCBs f the 
value of this field is zero. This field 
may be zeroed (remove a continuation) 
but no other values may be set (add a 
continuation) . 

Sequence number of the continuation FCB. 
For tape and tty FCBs f the value of this 
field is zero. This field may be zeroed 
(remove a continuation) but no other 
values may be set (add a continuation) . 
Usage ID field. The type of FCB. Values are: 



fcbunalloc 







febextuseent 



This FCB is unused. The 
data in this record is 
invalid. 

This record contains a 
root FCB. 

This record contains a 
continuation FCB. 
Number of extent fields in use within this FCB. 



fcballocroot 



fcballoccont 



The format of the last 
.242 bytes of the FCB 
is different for 
"primary" FCBs as 
opposed to 

"continuation" FCBs. 

For primary FCBs 

(disk, tape and tty) 

the format is as 

follows: 
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fcbf iletype 



fcbf ilename 

fcbf ileext 
fcbf ilevers 
fcbdirfcfcnum 

fcbdirseqnum 
fcbrecordsz 



fcbuserid 

fcbgroupid 

fcbprotect 



fcbcreatemstim 



fcbcreatelstim 



File type. This can be changed without 
privileges. For tty files f it is always set 
to zero (a data file). Valid file types are: 
File Type Value Description 



fcbftdata 

fcbftdir 

fcbf timge 

fcbftksamdata 

fcbftksamkey 

fcbftllimage 

fcbftarchcont 

fcbftencrypt 

fcbftsystem 

fcbf tar chive 



data file 

1 directory file 

2 image file 

3 KSAM data file 

4 KSAM key file 

5 LL image file 

6 archive file continuation 

7 encrypted file 

8 system file 

9 archive file 
20-255 reserved 

256-65535 user-defined file types 
Filename. For disk and tape files it 
contains the filename portion of the 
file designation. For tty files it 
contains, the devicename. 
File extension. For tty FCBs this field 
is set to zero. 

File version number. For tty FCBs this 
field is set to zero. 

Directory FCB number. The FCB number of 
the directory file containing this file. 
For tape and tty FCBs it contains zero. 
Directory sequence number. The sequence 
number of the directory file containing 
this file. For tty FCBs this field 
contains zero. 

Default record size. This can be changed 
without privileges. For tty FCBs this 
field is set to 1. 
Owner ID of the file's owner. 
Group ID of the file's owner. 

File protection field. This can be 
changed without privileges. For tty 
FCBs it contains the device protection. 
The most significant 32 bits of the file 
creation date in system time format 
(year and day) . For tty FCBs, it 
contains the year and day that the 
device was mounted. 

The least significant 32 bits of the 
file creation date in system time format 
(hour, minute, ...). For tty FCBs, it 
contains the hour, minute, ... that the 
device was mounted. 
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f cfcmodnstim 



fcbnodLstim 



fcbreserved 4 

fcbphysicalsz 4 

fcblogicalsz 4 



fcbf ileid 



fcbrootexthlk 180 



fcbnotcksum 



The most significant 32 bits of the date 
the file was last modified (year and 
day) . For tty PCBs, it contains the year 
and day that the device was mounted. 
The least significant 32 bits of the 
date the file was last modified (hour, 
minute, second, tick) . For tty PCBs, it 
contains the hour, minute, . . . that the 
device was mounted. 
Reserved space. 

The physical size of the file in bytes. 
For tty FCBs this field is set to zero. 
The logical size of the file in bytes. 
This can be changed without .privileges. 
For tty FCBs this field is set to zero. 
File ID of the file. This can be changed 
without privileges. For tty FCBs this 
field is set to zero. 
File extent fields. There are 30 extent 
fields in a primary FCB. Each extent 
field is composed of 6 bytes. The first 
two bytes represent the number of 
sectors in that extent. The last four 
bytes are the logical sector number of 
the first sector in that extent. 
The FCB's NOTted checksum. 



The format of the last 242 bytes of the FCB for "continuation" 
FCBs (disk only) is as follows: 



fcbcontextblk 240 



fcbnotcksum 



File extent fields in a continuation FCB. 
There are 40 extent fields in a continuation 
FCB. Each extent field is composed of 6 bytes. 
The first two bytes represent the number of 
sectors in that extent. The last four bytes 
are the logical sector number of the first 
sector in that extent. 
The FCB's NOTted checksum. 



Related Privileges: 

none - Cannot write the FCB 

writephys - Allows the process to update the FCB if the process 
also has write access to the file. 
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lun - Logical unit number of the file whose PCB is being 

updated, 
cont - Which part of the FCB for this file is to be updated. 

0=root FCB, l=first continuation FCB, etc. 
fcbuf f - Address of a 256-byte buffer containing the FCB to be 

written. This buffer must be word aligned, 
status - Address of a long word to receive the result of the 

operation. 



Diagnostics: 



errinsufpriv (1) 

erridxrange (56) 

errinvlfn (132) 

errnowriteacc (142) 



The process lacks the privileges required to 

perform the operation. 

The tabLe ends before the specified occurrence. 

Hie logical unit number does not correspond to 

an open file. 

The process does not have write-access to the 

specified file. 



See Also: 



_create - Create a file 
_getfcb - Get file control block 
_ppen - Open a file 
__setfprt - Set file protection 



Assembler Calling Sequence: 



push 


lun 


push 


cont 


push 


fcbuff 


push 


status 


jsr 


_setfcb 



; value - logical unit number 
;value - continuation FCB number 
;address - buffer containing FCB 
;address - result of the operation 
;write file control block 



C Function Declaration: 



#include "sys$disk/sysincl. sys/f cbdisp. h" 

/* write file control block */ 

long /* returns result of the operation */ 

_setfcb(lun, cont, fcbuff) 

long lun; /* logical unit number */ 

long cont; /* continuation FCB number */ 

fcbtype fcbuff; /* buffer containing FCB */ 
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FORTRAN Subroutine Declaration: 



I write file control block 



subroutine setfcb(lun, cont, fcbuff, status) 
integer*4 lun i logical unit number 

integer*4 cont 1 continuation FCB number 

character* (*) fcbuff ! buffer containing FCB 
integer*4 status ! result of the operation 



Eascal Procedure Declaration: 



%%sy s$disk/sy sincl . sy s/f cbdisp. pas 



procedure _setf cb 
lun 
cont 
fcbuff 
var status 

) ; external ; 



{** write file control block} 
longint; {** logical unit number} 

longint; {** continuation FCB number} 

~array__of_char ; {buffer containing FCB} 
longint {** result of the operation} 
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_wake 

Wake a hibernated process. 

Description: 

Zeros the hibernate count and clears the hibernate status bit 
in the process control block of the specified process. In other 
words the process will be awakened no matter how many times it 
has been hibernated. No error occurs if the process being 
awakened is not hibernating. Note that a process cannot wake 
itself since a hibernating process cannot make the call. 

Related Privileges: 



none 
group 
world 
Parameters : 



- Allows waking any process with the same owner id and 
group id as the calling process. 

- Allows waking any process with the same group id as 
the calling process. 

- Allows waking any process. 



pid - This is a long word uniquely specifying the process 

id of the process to wake up. The high word refers 
to the site ID f with representing the node you are 
on. The low word refers to the process: a process id 
of -1 refers to the parent of the calling process, -2 
is undefined, and -3 wakes all processes. 

status - Address of a long word to receive the result of the 
operation. 



Diagnostics: 

errinsufpriv 
errprcsnotfnd 



(1) The process lacks the privileges required 
to perform the operation. 

(2) The specified process is not in the system 
process table. 
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wake 



See Also: 



_hibern - Hibernate a process 

_wakec - Wake a hibernated process with count 



Assembler Calling Sequence: 



push 


pid 


push 


status 


jsr 


_wake 



;value - process id 

;address - result of the operation 

;wake a hibernated process 



C function declaration: 



/* wake a hibernated process */ 
long /* returns result of the operation */ 

_wake (pid) 

long pid; /* process id */ 

Fortran Subroutine Declaration: 

c I wake a hibernated process 

subroutine wake (pid, status) 

integer *4 pid I process id 

integer *4 status I result of the operation 

Pascal Procedure Declaration: 

procedure _wake( {** wake a hibernated process} 
pid : longint; {** process id} 

var status : longint {** result of the operation} 

) ; external; 
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What would you delete from the manual and why? 






What areas need greater emphasis? 







List any terms or symbols used incorrectly. 
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